Reference Manual
****************

This manual is the complete description of GDL. The style is somewhat terse; for more detail on how to use GDL to design games, see Chapter 3.

Symbols followed by ?? have not been implemented yet, so they should be considered as subject to change.

Language Syntax
===============

GDL resembles Lisp, but instead of defining functions, the contents of a file declare certain objects (such as units and unit types) to exist and specify their content. In other words, GDL is nonprocedural. This means that most of the time, you can list the various forms in any order you like. The main restriction is that any symbol, such as a variable or the name of a type, has to be defined before it is used. Also, forms such as set and add, that set the value of a variable or property, always overwrite the previous data irreversibly, so ordering of these is very important.

Lexical Elements
----------------

Numbers are introduced by a decimal digit, plus, or minus signs. They may contain only decimal digits, a decimal point, and be followed (immediately, no whitespace allowed) by a percent sign or a recognized unit of measure.

Strings are sequences of characters enclosed by doublequotes ("). They may contain any character except ASCII NUL ('\0'). To include a doublequote, use backslash, as in "a \"quoted\" string". To include a nonprinting or eight-bit character, use backslash followed by three octal digits, which will be interpreted as an eight-bit character code. (This is mostly the same syntax as in C.) Note that game design files may be passed over networks and between different kinds of computer systems, so non-ASCII characters should not be inserted verbatim into strings.

Symbols are sequences of characters that don't include any of the other special characters.  If you wish to include such characters in a symbol, enclose it in vertical bars, for example |foo bar|. (The bars are not part of the symbol.) Symbols are case-sensitive, but this will be changed eventually.

Lists are a sequence of expressions enclosed in parentheses. The empty list is either nil or (). ``Dotted pairs'' are not allowed. Anything that is not a list is an atom.

All of these objects may range up to a very large size. (You may still run into bugs if you make strings or symbols over about 100 chars in length.)

Comments are enclosed either within #| |# (which nests properly,
like Common Lisp and unlike C), or else extend from a semicolon
; to the end of the line.  A comment is equivalent to whitespace,
so (a#|bcd|#e) is the same as (a e).

[# by itself is a special token]

True/false values are just the integers 0 and 1, with no special characteristics.

 -- GlobalConstant: true

 -- GlobalConstant: false
     These constants are symbolic forms for 1 and 0. They are identical to numbers, but more descriptive for parameters that are boolean-valued.

Unit, material, and terrain types are distinct objects.

Conventions Used
----------------

Descriptions of values in this manual follow the conventions listed here.

For parameters described as T/F, both 1, 0 and true, false may be used. Parameters described as N and N% are numbers. Parameters described as DIST or LENGTH are also numbers, but are in the unit of measure for lengths. Parameters described as STR or STRING are strings.

Parameters described as U or UI, M or MI, and T or TI, are values that must be unit, material, or terrain types, respectively.

Parameters described as UTYPE-VALUE-LIST match unit types with values. They can have several forms:

  * (n1 n2 ...) matches n1 with type 0, etc in order.

  * ((u1 n1) (u2 n2) ...) evaluates u1 to get a unit type, then matches it with n1.  u1 etc may also be a list of types, in which case all the types get matched with n1.

Other types of lists, such as those defined as SIDE-VALUE-LIST, are interpreted similarly.

Forms and Evaluation
--------------------

A form is either any single expression that appears in the file. A GDL file consists of a sequence of forms. Most forms of interest will be lists. whose first element is a symbol identifying the form. For instance, a form beginning with the symbol side declares a side object. When the file containing such a form is read, Xconq will create a side object and fill in any properties as specified by the form. (Properties are like properties or attributes - most kinds of objects have some.)

In most contexts, Xconq will evaluate an expression before using it, such as when filling in an object's property. Numbers and strings evaluate to themselves, while symbols evaluate to their bindings. Lists evaluate to the same list, but with all the elements evaluated.

Tables
------

A table is a two-dimensional array of values indexed by types. Indices can be any pair of unit, material, or terrain type. The set of tables is fixed by Xconq, and all are described below.

 -- Form: table table-name items...
     This is the general form to fill in a table. The table named by TABLE-NAME is filled in from the ITEMS. If an item is an atom, then every position in the table is filled in with that item, overwriting any previously-specified values. If an item is a list, it must be a three-element list of the form (TYPE1 TYPE2 VALUE). If both TYPE1 and TYPE2 are single types, then VALUE will be put into the table at the position indexed by the two types. If one of TYPE1 or TYPE2 evaluates to a list, Xconq will iterate over all members of the list while keeping the other type constant, while if both TYPE1 and TYPE2 are lists, then Xconq will iterate over all pairs from the two lists. The values used during iteration depend on whether the VALUE is a list.  If VALUE is an atom, then that value will just be used on every iteration.  If a list, then Xconq will use successive elements of the list while iterating.

The following forms are all equivalent:

     (table foo (a y 1) (b y 2) (c y 3) (a z 9) (b z 9) (c z 9))

     (table foo ((a b c) y (1 2 3)) ((a b c) (z) 9))

     (define v1 (a b c))
     (table foo (v1 y (1 2 3)) (v1 z 9))

     (table foo ((a b c) (y z) ((1 2 3) (9 9 9))))

Modifying Objects
-----------------

Since forms normally define or create new objects, GDL defines the add form to modify existing objects.

 -- Form: add objects property new-values...
     This form evaluates the atom or list OBJECTS to arrive at the set of objects to be modified. Then it uses the NEW-VALUES to write new data into the property named PROPERTY of those objects. The NEW-VALUES may be a single number or string, or a list.

     If OBJECTS is the symbol table, then this form adds to a table instead.

Symbols
-------

Most of the symbols used in a game module are the predefined ones described in this manual. Others are attached to types when the types are defined, and still others name objects like units and sides. You can also define and set your own symbols to arbitrary values.

 -- Form: define symbol value
     This form defines the symbol SYMBOL to be bound to the result of evaluating VALUE. If SYMBOL is already defined, Xconq will warn about it, and ignore this form.

 -- Form: set symbol value
     This form rebinds the already-bound symbol SYMBOL to be bound to the result of evaluating VALUE. If SYMBOL is not bound already, then Xconq will warn about it, but proceed anyway.

 -- Form: undefine symbol
     This form destroys any binding of the SYMBOL. This is allowed for any symbol, including already-unbound symbols.

Lists
-----

 -- Operation: quote xxx...
     This operation prevents any evaluation of XXX.

 -- Operation: list xxx...
     This operation makes a list out of all the XXX.

 -- Operation: append xxx...
     This operation appends all the XXX (which may be lists or not) into a single list.  Non-lists will appear as though they were single-element lists.

 -- Operation: remove list1 list2
     This operation removes the members of LIST1 from LIST2.

Game Modules
============

The game module declaration supplies information about the file as a whole. It is optional; if missing, Xconq will get the module's name from its file name, and supply defaults for the other properties.

 -- Form: game-module [name] properties...
     This form defines the properties of this game module. The optional NAME is a string that will be used to look up the module in libraries. If the NAME is supplied, then this form is considered to be the definition of the module, and overwrites any game-module form previously appearing in this file. If NAME is missing, then this form will modify the existing description of the module.

 -- ModuleProperty: title string
     If defined, this property is the name by which the module will be displayed to players.  It is not used internally, so the name can be modified freely (unlike the module's name, which may appear in other modules). Defaults to the module's name.

 -- ModuleProperty: blurb string
     This property is a one-line description that users will see when they are deciding whether to play the module. It will be displayed without any modification:

          Welcome to my nightmare! (version 1.0 with stronger goblins)

     Defaults to "".

 -- ModuleProperty: picture-name string
     This property is the name of a picture that may be displayed along with the module's blurb, by those interfaces that support such pictures. Defaults to "".

 -- ModuleProperty: base-game t/f

 -- ModuleProperty: instructions strings...
     This property is a list of strings that are the instructions on how to play the game.  Defaults to ().

 -- ModuleProperty: notes strings...
     This property is a list of strings comprising the set of detailed player's notes for the module. Both the list and each string in the list can be of any length. When displayed, the strings are all concatenated together, so the division into strings here is just for convenience. How these are displayed is up to the interface, but in general an empty string signals a new paragraph. Defaults to ().

 -- ModuleProperty: design-notes strings...
     This property is a list of strings that are notes addressed to game designers. Defaults to ().

 -- ModuleProperty: version string
     This property is the version of the module. Defaults to "", which indicates that the module's version is undefined.

 -- ModuleProperty: program-version versions
     This property dentifies Xconq versions for which this module is appropriate. If specified, then players will get a warning if they attempt to use this module with an inappropriate version of Xconq. Possible forms include a string, which allows the module only for exactly matching version of Xconq, and (COMPARISON VERSION), which allows versions satisfying the COMPARISON test, which may only be >= or <=. So for instance

          (game-module "foo" (program-version (>= "7.0.3")))

     is claimed to only work for versions 7.0.3 or later. Defaults to "", which means that the module is appropriate for any version of Xconq.

     Notes that the program-version is strictly a heuristic to forewarn players; in practice it can be very difficult to know which modules work with which programs.  (The problems are similar to those encountered by programmers using different compiler versions on their programs.)

 -- ModuleProperty: variants items...
     This property defines named variants on this module. Variants appear as startup options for the game. The items have the form ([NAME] TYPE [DATA]). The NAME is a string or symbol used to identify the choice to the players, the TYPE says what sort of change is being enabled, and DATA supplies a range of values or content. The different types of variants are listed below. A game module may specify any number of variants. Defaults to ().

 -- VariantType: eval forms
     If this variant is chosen, execute the FORMS.

 -- VariantType: number [form sym [lo dflt hi]]
     Replace occurrences of the symbol SYM in FORM to a value ranging between LO and HI, defaulting to DFLT, then evaluate FORM.

 -- VariantType: flag variable dflt

 -- VariantType: world-size [width [height [circumference]]]
     This variant allows players to choose the size of the world. The sizes will default to the values in this variant's data. (WIDTH and HEIGHT can be lists of the form (lo dflt hi), with the obvious interpretation??)

 -- VariantType: world-seen dflt
     This variant allows players to choose whether the terrain of the world will be known at the start of the game. The default setting will be the value dflt, which may be either true or false.

 -- VariantType: see-all dflt
     This variant allows players to choose whether everything will be seen always, as with the global variable see-all. The default is set by dflt.

 -- ModuleProperty: base-module name
     This property is the name of a module that must be loaded first. It is similar in effect to include.

 -- ModuleProperty: default-base-module name
     This property specifies the name of a module that will be loaded if this module is given as the ``top-level'' module, such as via -g on a command line.

     This is to prevent disasters when a library module that is used only by other modules is instead loaded as if it were a full game design.

Including Other Modules
-----------------------

You can include one game module in another.

 -- Form: include [if-needed] module-name [variant-settings]
     This form has the effect of inserting the contents of MODULE-NAME into the current position in the module. game-module forms in the included module are not inserted, although they are remembered and may appear in displays. Xconq will fail completely if the included module cannot be found.

     Unlike C etc, the same module cannot be included more than once; you will get a warning and the module will not be loaded.

Note that the module names are not file names, so that system-specific features like directories and devices cannot be included. The mapping between module name and file name is interface-specific, so if you want to distribute a module, you should make sure all the module names don't have anything nonportable embedded. Alphanumeric characters and hyphens are guaranteed to be portable.

Conditional Loading
-------------------

[not really implemented yet - need a conditional stack, check matching end, complain if no match - add do/skip flag to interp_form]

 -- Form: if sym test-form

 -- Form: else sym

 -- Form: end-if sym

The World
=========

The world consists of a set of areas (only one at present), each of which is regular in shape and consists of a number of cells. Each cell has a type of terrain and a number of optional pieces of data. Each kind of per-cell data will be called a layer of the area.

 -- Form: world [circumference] properties...
     This form defines the properties of the world as a whole.

 -- WorldProperty: circumference dist
     This property is the distance around the entire world (as a sphere). Default is 360.

 -- WorldProperty: axial-tilt n
     This property defines the extremes of seasonal changes.

 -- Form: area [width [height]] [restriction] properties...
     This form defines the playing area of the world. The RESTRICTION identifies how to get data for this area from subsequent forms that are based on larger areas.

 -- AreaRestriction: restrict w h x y
     This is a special form that specifies that subsequent layers in an area of size w x h will be offset by x,y and then read into the actual area.  [obscure explanation, see the library for examples]

 -- AreaProperty: width n

 -- AreaProperty: height n
     These properties are the width and height of the world, as measured in cells. Allowable values range from 3x3 up to 32767x32767, which is one billion cells! If only one of these is given, then the other defaults to the same value. If neither has been given, then they default to 60 and 30, respectively.

In the case of a cylinder, the world wraps around in the x direction, and the width is the diameter of the cylinder, while the height is just the height in the usual sense. A hexagon world is flat on the top and bottom; its width is measured across the middle height, which is the largest span, and height is the same as for cylinders.  Here are some crude pictures, first of an 8x6 cylinder:

     # # # # # # # #
      : : + + : : : :
     : : : + ^ : : :
      : : : : : : : :
     : : : : ^ : : :
      # # # # # # # #

This world is an 8x7 hexagon:

        # # # # #
       # : + + : #
      # : : + ^ : #
     # : : + ^ : : #
      # : : : : : #
       # : : ^ : #
        # # # # #

There are two kinds of properties that an area may have: scalar values such as latitude, and layer values such as terrain and elevation.

 -- AreaProperty: latitude n
     This property is the offset from the equator of the middle of the area (height / 2). Defaults to 0.

 -- AreaProperty: longitude n
     Defaults to 0.

Layers
------

Layers constitute the bulk of data about an area of the world. Each layer assigns a value to each cell in the area; examples include cell terrain, temperatures, elevations, and so forth. Since there may be many cells in a layer with the same values, each layer uses a common run-length encoding scheme. In this scheme, each horizontal band of cells is a separate text string, and the contents of the string encode individual numeric values, one for each cell. The encoding uses the characters a..~ and :..[ for 0 through 63, and decimal digits followed by commas (or the end of the string) for all other numbers. Runs of constant value are prefixed with their length, in decimal. Thus, the string

     "40adaa100,2*-99"

represents 46 values in all: 40 zeroes, a three, 2 more zeros, a 100, and two -99s. Although this format is totally unreadable, it has the advantages of compactness and portability; the expectation is that most layer editing will be done on-line. Note that the run encoding is entirely optional.

The following subforms at the beginning of layer data have special effects:

 -- LayerSubform: constant n
     This subform causes every value in the layer to be set to N.

 -- LayerSubform: subarea x y w h
     This subform indicates that the layer data should be positioned at the given rectangle in the layer.

 -- LayerSubform: xform mul add
     This subform has the effect of first multiplying the raw value by MUL, then adding ADD and storing the result into the layer.

 -- LayerSubform: by-bits

 -- LayerSubform: by-char str
     This subform specifies that the characters in STR give the encodings of values in the layer. The first character in STR encodes 0, the second encodes 1, and so forth.

 -- LayerSubform: by-name name-list
     [what is the syntax of name-list exactly?] This subform is for generic worlds that are useful across multiple game designs. The value/name pairs allow for the matching of terrain types by name, so that if, say, the ``sea'' terrain type was type #0 in one game and type #4 in another, the world would have sea in all the same places after it was read in. In practice, only a few worlds are this general. If a named terrain type is not present, Xconq will warn about it and substitute type 0.

 -- AreaProperty: terrain layer-data...
     This property is the actual layer of terrain types for cells.

 -- AreaProperty: aux-terrain terrain-type layer-data...
     This property fills in values for borders, connections, and coatings. For border and connection terrain, the value is a six-bit number (0..63), with a bit turned on in each direction that there is a border or connection. For coating types, the value is the depth of the coating.

 -- AreaProperty: features feature-list layer-data...
     This property specifies the nature and location of all geographical features. The FEATURE-LIST is a list of lists, where each sublist has the form ([ID] TYPENAME NAME [SUPER]) where ID is the numerical id referenced in the layer data (defaults to feature's position in the FEATURE-LIST), TYPENAME is a symbol or string giving the general type of feature (such as bay), NAME is the name of the feature (such as "Bay of Bengal"), and SUPER is the optional id of another feature that incorporates this feature.

 -- AreaProperty: material material-type layer-data...
     This property declares the quantity of the given MATERIAL-TYPE in each cell of the area.

 -- AreaProperty: people-sides layer-data...
     This property says which side the people of each cell are on. A SIDE-ENCODING of exact assigns 0 to independence (no side), 1 to the first side, and so forth; otherwise, the encoding is a list of side names/ids and numbers.

Distances and Elevations
------------------------

 -- AreaProperty: elevations layer-data...
     This property is the world elevation data itself. If any elevation falls outside the min/max elevation range for the terrain type of the cell, then it will be truncated appropriately. Defaults to 0 for each cell.

 -- AreaProperty: cell-width dist
     This property is the distance across a single cell, expressed as units of elevation.  Defaults to 1. [this *must* be a long...]

Temperatures
------------

Each type of terrain has a temperature range in which it may be found. Any calculation that would fall outside this range will be clipped.

The temperature can be set to have a given value at a given elevation. All air temperatures will be interpolated appropriately.

 -- GlobalVariable: temperature-floor n
     This variable is the lowest possible temperature. Defaults to 0.

 -- GlobalVariable: temperature-floor-elevation n
     This variable is the elevation at which the temperature is always at temperature-floor. Defaults to 0.

 -- AreaProperty: temperatures layer-data...
     This property contains the temperature data itself. If any temperature falls outside the min/max temperature range, then it will be truncated appropriately. Defaults to 0 for each cell.

Winds
-----

Winds are defined as having a nonnegative force and a direction.

 -- AreaProperty: winds layer-data...
     This property contains the force and direction of the prevailing winds in each cell.

Clouds
------

 -- AreaProperty: clouds layer-data...

 -- AreaProperty: cloud-bottoms layer-data...

 -- AreaProperty: cloud-heights layer-data...

Sides
=====

 -- Form: side [id] properties...
     This form has the effect of declaring a side to exist. If the number or symbol ID is supplied and matches that of a side that has already been created, then the properties will modify the pre-existing side. Otherwise a new side object will be created, with a arbitrarily-chosen numeric id ranging between 1 and sides-max. If the given ID is a symbol, then the side object will be bound to that symbol.

 -- GlobalVariable: sides-min n

 -- GlobalVariable: sides-max n
     These variables are the minimum and maximum number of sides that may exist in a game.  Defaults are to 1 and the internal parameter MAXSIDES, which is usually around 7. MAXSIDES can only be changed by recompiling Xconq.

 -- Form: side-defaults properties...
     This form sets the defaults for all newly-created sides declared subsequently. These defaults will be set before the new side's properties are interpreted. This form has no effect on existing sides or on side declarations that modify existing sides.

Name and Related Properties
---------------------------

If the game design allows, all of these properties can be set at startup by the players (see <side config> and below). Omission of some of these results in suppression or substitution, depending on the interface and the situation. Omission of all name properties allows the side to go unmentioned, which is useful when the concept of ``side'' is useless or confusing to a player (as in some adventure games). All of these properties may be set at any time by any player.

 -- SideProperty: name str
     This property is the proper name of a side, as a country or alliance name. Examples include "Axis" and "Hyperborea". Defaults to "".

 -- SideProperty: long-name str
     This property is the long form of a side's name, as in "People's Republic of Hyperborea". Defaults to be the same as the side's name.

 -- SideProperty: short-name str
     This property is an short name or acronym for the side, often just the letters of the long name, as in "PRH". Defaults to "".

 -- SideProperty: noun str
     This property is the name of an individual unit or person belonging to the side. Defaults to "", which suppresses any mention of the side when (textually) describing the individual.

 -- SideProperty: plural-noun str
     This property is what you would call a group of individuals. Defaults to the most common plural form of the noun (in English, the default pluralizer adds an ``s''), so any alternative plural noun, such as "Chinese", will need an explicit plural-noun value.

 -- SideProperty: adjective str
     This property is an adjective that can be used of individuals on the side, as in "Spanish". Defaults to "", which suppresses use of the adjective.

As a complete example, a side named "Poland" would have a long name "Kingdom of Poland", short name "Po", noun "Pole", plural noun "Poles", and adjective "Polish".

 -- SideProperty: color-scheme str

 -- SideProperty: colors str

 -- SideProperty: color str
     This property is a comma-separated list of colors that represents the side. Defaults to "black".  (The three forms are just synonyms.)

 -- SideProperty: emblem-name str
     This property is the name of a graphical icon that represents the side. An emblem name of "none" suppresses any emblem display for the side. Defaults to "", which gives the side a randomly-selected emblem.

 -- SideProperty: names-locked t/f
     If the value of this property is true, then the player cannot modify any of the side's names. Defaults to false.

Side Class
----------

 -- SideProperty: class str
     This property is a side's class, which is a keyword that characterizes the side. Any number of sides may be in the same class.

Status in Game
--------------

Once a side is in the game, it can never be totally removed. However, sides can become inactive.

 -- SideProperty: active t/f
     This property is true if the side is still actively participating in the game. If the side has won, lost, or simply withdrew, this will be false. Any units on a side not in the game are effectively frozen statues; they don't do anything, and are untouchable by anyone else. Defaults to true.

 -- SideProperty: status lose/draw/win
     This property tells how this side did in the game.  Defaults to draw.

 -- GlobalConstant: win

 -- GlobalConstant: draw

 -- GlobalConstant: lose
     These constants are the different possible values for a side's status.

 -- SideProperty: advantage

 -- SideProperty: advantage-min

 -- SideProperty: advantage-max

Side Relationships
------------------

By default, sides are neutral with respect to each other.

Control is a situation where one side can observe and move another side's units, but not vice versa. The controlling side can also just take the units of the controlled side. If the controlled side loses or resigns, then the controlling side automatically gets everything. Both sides must agree to this relationship.

 -- SideProperty: controlled-by side
     This property refers to the side controlling this one. If 0, then the side is not under control. Defaults to 0.

The closest side relationship is one of trust. A trusted side unit's may do anything at any time, including entering and leaving units on the other side, consuming the other side's materials, and so forth.

 -- SideProperty: trusts side-value-list
     This property is true for any side that is trusted by this side. Note that this relationship need not be symmetrical. Defaults to false for all sides.

Note that these parameters apply only to relationships as enforced by Xconq.  In an actual game, both human and robot sides can make agreements and have positive/negative opinions about the other sides.

 -- SideProperty: trades side-value-list
     This property defines the trading relationship with other sides.

Numbering Units
---------------

 -- SideProperty: next-numbers utype-value-list
     This property gives the next serial numbers that will be assigned to units acquired by this side. Defaults to 1 for each unit type (Dijkstra notwithstanding, that's still where people start numbering things).

If the unit is of a type that gets numbered (assign-number property is true), then any unit of that type, acquired by any means whatsoever, will be assigned the next-numbers value for that type and next-numbers will be incremented.

Side-Specific Namers
--------------------

A side can have its own set of namers (see below) that will be used for units and geographical features associated with that side.

 -- SideProperty: unit-namers utype-value-list
     This property specifies which namers will be used with which types that the side starts out with or creates new units. These will not be run automatically on captured units or gifts. Defaults to "" for each unit type.

 -- SideProperty: feature-namers feature-type-value-list
     This property specifies which namers to use with which geographical features in the side's initial country (if if has one). Defaults to ().

Tech Levels
-----------

The tech level of a side determines what it can do with each type of unit.

 -- SideProperty: tech utype-value-list
     This property assigns a tech level to each unit type named. Defaults to 0 for each unit type.

 -- SideProperty: init-tech utype-value-list
     This property is the tech level at the beginning of the current turn. Defaults to 0 for each unit type.

Views
-----

These properties are necessary only if the relevant globals are set a certain way (see-all is false, etc).

 -- SideProperty: terrain-view layer-data...
     This property is the side's current knowledge of the world's terrain. Defaults to ().

 -- SideProperty: unit-view layer-data...
     This property is the side's current knowledge of the world. Defaults to ().

 -- SideProperty: unit-view-dates layer-data...
     This property is the turn number at which the unit view data in the corresponding cell of the unit-view was set. Defaults to ().

Interaction
-----------

 -- SideProperty: turn-time-used seconds
     This property is the number of (real) seconds that this side has been moving units during the present turn. Defaults to 0.

 -- SideProperty: total-time-used seconds
     This property is the number of (real) seconds that this side has been moving units during the course of the game. Defaults to 0.

 -- SideProperty: timeouts n
     This property is the number of ``time outs'' a side gets for the game. Defaults to 0.

 -- SideProperty: timeouts-used n
     This property is the number of ``time outs'' a side has already used up. Defaults to 0.

 -- SideProperty: finished-turn t/f
     This property is true if the side has declared that it is finished moving things during this turn. Defaults to false.

 -- SideProperty: willing-to-draw t/f
     This property is true if the side will go along with any other side that wants to end the game. Defaults to false.

 -- SideProperty: ai xxx
     This property is information about the AI associated with a side. Defaults to ().

 -- SideProperty: respect-neutrality t/f

 -- SideProperty: real-timeout seconds
     This property is the number of (real) seconds to wait before declaring the side to be finished with this turn. Defaults to -1, which waits forever.

 -- SideProperty: real-time-used seconds
     This property is the total number of seconds used by this side already in the game.

 -- SideProperty: task-limit
     This property is the maximum number of tasks a unit is allowed to stack up.

Doctrine
--------

Doctrines are objects that units consult to decide about individual behavior.

 -- SideProperty: doctrines utype-property-groups...
     This property is the side's unit-type-specific doctrine. Each UTYPE-PROPERTY-GROUP has the form (UNIT-TYPES properties...). Defaults to ().

 -- SideProperty: doctrines-locked t/f

 -- Form: doctrine [id] properties...
     This form creates a doctrine with the given id and properties.

 -- DoctrineProperty: ever-ask-side t/f
     This property is the true if the unit may ask the player for what to do, instead of picking some default activity.

 -- DoctrineProperty: avoid-bad-terrain n%
     This property is the probability that the unit will not enter unhealthy terrain, even if it delays meeting goals. Unhealthy means higher attrition and accident probs, materials consumed faster than replaced, slower movement. Defaults to 0.

 -- DoctrineProperty: repair-at n%
     This property indicates that when the unit's hp is at N% of max, make a plan to repair. Defaults to 50.

 -- DoctrineProperty: resupply-at n%
     This property indicates that when the level of a operationally-consumed material is at N% of capacity, try to resupply. Defaults to 50.

 -- DoctrineProperty: rearm-at n%
     This property indicates that when the level of a combat-consumed material is at N% of capacity, try to resupply. Defaults to 50.

 -- DoctrineProperty: fill-percentage n%
     This property indicates that when a transport is waiting for occupants, plan to wait until the number of occupants is this percentage of capacity. Defaults to 80.

 -- DoctrineProperty: expendability n
     This property is the odds at which a unit will be willing to attack.

 -- DoctrineProperty: locked t/f
     This property is true if the doctrine cannot be modified by the player. Defaults to false.

Other
-----

 -- SideProperty: self-unit unit
     This property is the id of a unit that represents the side itself. Defaults to 0, which means that no unit represents the side. See below for more details on self units.

 -- SideProperty: priority n

 -- SideProperty: scores list

 -- Form: independent-units properties...
     Like the side form, but sets properties for independent units.

 -- SideProperty: ui-prefs
     This property contains interface-specific data for the side. This is mainly for preservation across game save/restores, and its form is defined by the interface.

Players
=======

Player objects are rarely necessary when building game designs; they typically only appear in saved games, in order to ensure that the same players get the same sides upon restoration.

 -- SideProperty: player id
     This property is the unique identifier of a player that is running this side. Defaults to 0, which means that no player has been assigned to the side.

 -- Form: player [id] properties...
     This form defines players. If the ID is supplied and matches an existing player id, then the player object is updated using the PROPERTIES, otherwise a new player object will be created, using the given ID if supplied.

 -- GlobalVariable: player-sides-locked t/f
     This variable is true when the player/side assignment may not be changed while the game is starting up. Defaults to false.

The number of players must always be less than the number of sides (sides without players just don't do anything).

 -- PlayerProperty: name str
     This property identifies the player by name. Defaults to "".

 -- PlayerProperty: config-name str
     This property identifies a particular set of doctrine and other definitions that the player is using. Defaults to "".

 -- PlayerProperty: display-name str
     This property identifies the display being used by the player's interface. Defaults to "".

 -- PlayerProperty: ai-type-name str
     This property is the type of AI that will play the side if requested or necessary. The set of choices depends on what has been compiled into Xconq. (The general-purpose AI type "mplayer" will usually be available, but is not guaranteed.) An ai-type-name of "" means that no AI will run this player. Defaults to "".

 -- PlayerProperty: password str
     This property is the encoding of a password that must be entered before this player object can be reused successfully. Defaults to "".

 -- PlayerProperty: initial-advantage n
     This property is an initial relative strength at which the player should start. Some synthesis methods can use this to give more units or some other advantage to each player according to the requested strength. Defaults to 1.

 -- GlobalVariable: advantage-min n

 -- GlobalVariable: advantage-max n

 -- GlobalVariable: advantage-default n
     These variables set the bounds and default values for players' initial advantages. An advantage-max of 0 means that there is no upper bound on initial advantage (however, Xconq syntheses may not be able to synthesize such a game). Default to 1, 0, and 1.

Rules of Side Configuration
---------------------------

The properties of a side can come from a number of different sources (here listed in order of precedence):

  * Interface-specific sources (X resources, Mac preferences).

  * Game-specific form in side config file (matched by module name).

  * Generic form in side config file.

  * The side form for the side.

  * The side-defaults form.

  * General program defaults.

Note that interface-specific and general config files can never alter certain properties of a side, and can only alter others if they are not locked.

Units
=====

The basic unit form creates or modifies a unit.

 -- Form: unit id [type] properties...
     This form defines a unit. If a numeric ID is supplied and matches the id of an existing unit, then that unit will be modified by PROPERTIES, and the optional TYPE will be interpreted as a new type for the unit. Otherwise a new unit will be created, with either ID as its id or a arbitrarily-selected one if ID is already in use. If the unit's id is newly-generated and no type has been specified, then type #0 (first-defined type) will be the type of the unit. An id of 0 can never match an existing unit id, so effect will be as if it had been omitted.

 -- Form: UNIT-TYPE-NAME x y [side-id] properties...
     This is an abbreviated form, in which the x,y position is required, and an optional side id may be included. The UNIT-TYPE-NAME may be any valid unit type name or defined name.

Since there may be many units whose properties are similar, there is a ``default unit'' whose properties fill in missing properties in individual unit declarations.

 -- Form: unit-defaults reset properties...
     This form sets the default values for all subsequent units read in, in this and every other module not yet loaded. The set of defaults is additive, so for instance you can repeatedly change the default side of units. If the optional symbol reset has been supplied for RESET, then all the defaults will be changed to the basic default values, as described in this manual.

 -- Symbol: reset

Unit Properties
---------------

This section lists properties of individual units. In general, they default to the most common or reasonable values, so need not always be specified, even in a saved game.

 -- UnitProperty: @ x y [z]
     This property is the position of the unit. Defaults to -1,-1,0, which causes the unit to be placed randomly. The optional altitude Z can also be set separately with the property z below. If z is even and the unit is in the open, then the unit's altitude is z/2; if z is odd, then (z-1)/2 is the type of connection terrain that the unit is on.

 -- UnitProperty: z z
     This property is identical to the optional z part of the @ property. Defaults to 0.

 -- UnitProperty: s side
     This property is the side of the unit. It can be either a side name/noun/adjective (string) or id (number). A value of 0 or "independent" means that the unit is independent. Defaults to 0.

 -- UnitProperty: # n
     This property is the id of the unit. Defaults to a game-selected value.

 -- UnitProperty: n str
     This property is the name of the unit. Defaults to "".

 -- UnitProperty: nm n
     This property is the number of the unit, which starts at 1 and goes up. Defaults to 0, which means that the unit is unnumbered.

 -- UnitProperty: cp n
     This property is the current completeness of the unit. If negative, indicates that the unit will appear at a time and place specified by the appear x-property. Defaults to the cp-max for the type.

 -- UnitProperty: hp n
     This property is the current hit points of the unit. Will be restricted to the range [0, hp-max]. An hp of 0 means that the unit is dead and will not appear in the game. Defaults to hp-max for the unit's type.

 -- UnitProperty: cxp cxp
     This property is the combat experience of the unit. Defaults to 0.

 -- UnitProperty: m mtype-value-list
     This property is the amounts of supplies being carried by the unit. Defaults to 0 for each material type.

 -- UnitProperty: tp utype-value-list
     This property is the level of tooling to build each type of unit. Defaults to 0 for each unit type.

 -- UnitProperty: in n
     This property is the id of the unit's transport. Defaults to 0, meaning that unit is not in any transport.

 -- UnitProperty: feelings side-value-list...
     This property is the unit's true feelings towards each side, including its own side. Defaults to 0 for each side.

 -- UnitProperty: x obj
     This property is the optional extension properties of the unit. Its value may be any object. Defaults to ().

 -- Symbol: appear
     This is the extension property that indicates when and where a unit will appear in the game.

Unit Action State
-----------------

 -- UnitProperty: act subprops
     This property specifies the current action state of the unit.

 -- UnitActionStateProperty: acp n
     This property is the number of action points left to the unit for this turn. Defaults to 0.

 -- UnitActionStateProperty: acp0 n
     This property is the initial number of action points for this turn, computed at the beginning of the turn. Defaults to 0.

 -- UnitActionStateProperty: aa n
     This property is the actual number of actions executed by the unit so far in the current turn. Defaults to 0.

 -- UnitActionStateProperty: am n
     This property is the actual number of moves (cell entries) executed so far in the current turn. Defaults to 0.

 -- UnitActionStateProperty: a action
     This property is the next action that the unit will perform.

Note that if any unit-defining form has an act property, Xconq will start at an appropriate point in the middle of a turn, giving all other units zero acp and mp, rather than starting at the beginning of the turn and computing acp and mp for all units.

Unit Plan
---------

 -- UnitProperty: plan type [subtype] properties...
     This property describes the unit's current plan.

 -- PlanType: none
     A unit with this type of plan does nothing. It is used when a side has no player. [assume empty agenda, always asleep?]

 -- PlanType: passive
     This plan type is for when the side is being run by a human directly controlling all units.

 -- PlanType: defensive

 -- PlanType: exploratory

 -- PlanType: offensive

 -- PlanType: random

 -- PlanProperty: goal
     This property is the main goal of a unit's plan.

The possible types of goals are these:

 -- GoalType: won-game

 -- GoalType: lost-game

 -- GoalType: world-is-known

 -- GoalType: vicinity-is-known

 -- GoalType: positions-known

 -- GoalType: cell-is-occupied

 -- GoalType: vicinity-is-held

 -- GoalType: has-unit-type

 -- GoalType: has-unit-type-near

 -- GoalType: has-material-type

[also support some kind of hook for specific AIs?]

 -- PlanProperty: tasks tasks...
     This property is the complete task agenda for the unit's plan. It is a list of tasks. Defaults to ().

 -- TaskType: approach

 -- TaskType: ask-side

 -- TaskType: build u n n2 unit-id

 -- TaskType: capture unit-id

 -- TaskType: do-action action

 -- TaskType: hit-position x y z

 -- TaskType: hit-unit unit-id

 -- TaskType: move-dir dir

 -- TaskType: move-to x y z dist

 -- TaskType: occupy unit

 -- TaskType: pickup unit

 -- TaskType: repair unit

 -- TaskType: resupply

 -- TaskType: sentry n

 -- PlanProperty: asleep
     This property is true if the unit is asleep. Defaults to false.

 -- PlanProperty: reserve
     This property is true if the unit is in reserve. Defaults to false.

 -- PlanProperty: wait
     This property is true if the unit is waiting for orders. Defaults to false.

Agreements
==========

 -- Form: agreement [name/id] properties...
     This form defines an agreement among a set of sides. The name/id is a unique internal identifier.

 -- AgreementProperty: type-name str
     This property is the name of the general type of agreement, such a trade. Defaults to "".

 -- AgreementProperty: title str
     This property is the player-visible name of the agreement. Defaults to "".

 -- AgreementProperty: terms forms...
     This property is the list of terms of the agreement. Defaults to ().

 -- AgreementProperty: proposer side
     This property is the side that initially proposed the agreement.

 -- AgreementProperty: signers sides-list
     Before the agreement is made, this property is the proposed list of participants. After the agreeement is made, this is the actual list of participants.

 -- AgreementProperty: willing-to-sign side-list
     This property is all the sides that have already agreed to this agreement, on condition that all the other sides accept it.

 -- AgreementProperty: known-to side-list

 -- AgreementProperty: enforcement form

[include values such as enforced?? and publicity??]

 -- AgreementProperty: active t/f
     This property is true if the agreement is actually in effect. Defaults to true.

Scorekeepers
============

Scorekeepers are the objects that manage scoring, winning, and losing. A game design need not define any scorekeepers, and none are created by default. A scorekeeper may either maintain a numeric score that is used at the end of the game to decide rankings, or simply declare a side to have won or lost.

 -- Form: scorekeeper name properties...
     This form creates or modifies a scorekeeper with the given NAME, with the given PROPERTIES.

 -- ScorekeeperProperty: title str
     This property is a string that identifies the scorekeeper to the players. Defaults to "".

 -- ScorekeeperProperty: when (type [exp])
     This property is when the scorekeeper will be checked or updated. Defaults to after-turn.

 -- SKSym: before-turn exp
     This symbol indicates that the scorekeeper will run at the start of each turn matching EXP, or after every turn if EXP is not given.

 -- SKSym: after-turn exp
     This symbol indicates that the scorekeeper will run at the end of each turn matching EXP, or after every turn if EXP is not given.

 -- SKSym: after-event exp
     This symbol indicates that the scorekeeper will run after every event matching EXP, or after every event if EXP is not given.

 -- SKSym: after-action exp
     This symbol indicates that the scorekeeper will run at the end of each action matching EXP, or after every action if EXP is not given.

 -- ScorekeeperProperty: applies-to side-list
     This property is the set of sides or side classes to which the scorekeeper applies. Scorekeepers apply only to sides that are in the game. Defaults to side*.

 -- ScorekeeperProperty: known-to side-list
     This property is the list of sides that know about this scorekeeper, and can see the value of the score for each side that it applies to. Defaults to side*.

 -- ScorekeeperProperty: trigger form
     This property is an expression that is true when it is time to start checking the scorekeeper's main test. Once a scorekeeper is triggered, it remains active. Defaults to false.

 -- ScorekeeperProperty: triggered t/f
     This property is true if the scorekeeper is currently triggered. Defaults to true.

 -- ScorekeeperProperty: do forms...
     This property is a list of forms to execute in order each time the scorekeeper runs. Defaults to ().

 -- ScorekeeperProperty: initial value
     This property is the value of the score upon game startup. If this value is -9999, the scorekeeper does not maintain a numeric score. Defaults to -9999.

Bodies
------

The forms in the body (the do property) of the scorekeeper may be any of the forms listed here.

 -- SKSym: last-side-wins
     If supplied as the only symbol in the body, then the scorekeeper implements the usual ``last side left in the game wins'' behavior.

 -- SKSym: if test action
     If the test evaluates to true or any nonzero number, then the action will be done.

 -- SKSym: cond (test actions...) ...
     This is like Lisp's cond.

 -- SKAct: stop [message]
     This stops the game immediately, with a draw for all sides.

 -- SKAct: win [sides] [own-message] [other-message]

 -- SKAct: lose [sides] [own-message] [other-message]

 -- SKAct: end [message]
     This scorekeeper action ends the game immediately.

 -- SKAct: add exp [side]
     This adds the result of evaluating EXP to the score of the given side. The value may be a negative number.

Functions
---------

 -- SKSym: and exps

 -- SKSym: or exps

 -- SKSym: not exp

 -- SKSym: = exp1 exp2

 -- SKSym: /= exp1 exp2

 -- SKSym: > exp1 exp2

 -- SKSym: >= exp1 exp2

 -- SKSym: < exp1 exp2

 -- SKSym: <= exp1 exp2

 -- SKSym: sum types properties [test]

Scorefile
---------

 -- GlobalVariable: scorefile-name str

The History
===========

All the important events in a game are logged into a history.

 -- Form: evt [date] type data
     This form creates a single historical event. If date is omitted, then the date will be the same turn as for the last event read.

 -- EventType: log-started

 -- EventType: game-started

 -- EventType: side-joined

 -- EventType: side-lost

 -- EventType: side-withdrew

 -- EventType: side-won

 -- EventType: unit-started-with

 -- EventType: unit-created

 -- EventType: unit-completed

 -- EventType: unit-acquired

 -- EventType: unit-captured

 -- EventType: unit-moved

 -- EventType: unit-assaulted

 -- EventType: unit-damaged

 -- EventType: unit-killed

 -- EventType: unit-vanished

 -- EventType: unit-wrecked

 -- EventType: unit-garrisoned

 -- EventType: unit-disbanded

 -- EventType: unit-starved

 -- EventType: unit-left-world

 -- EventType: game-ended

 -- EventType: log-ended

 -- EventType: action-ok

 -- EventType: action-error

 -- EventType: cannot-do

 -- EventType: insufficient-acp

 -- EventType: insufficient-material

 -- EventType: not-implemented-yet

 -- EventType: action-done

 -- EventType: move-error

 -- EventType: insufficient-mp

 -- EventType: cannot-leave-world

 -- EventType: destination-too-far

 -- EventType: destination-full

 -- EventType: overrun-failed

 -- EventType: overrun-failed

 -- EventType: fire-into-outside-world

 -- EventType: fire-into-too-far

 -- EventType: fire-at-too-far

 -- EventType: fire-into-too-near

 -- EventType: fire-at-too-near

 -- EventType: too-far

 -- EventType: too-near

Battle States
=============

Battles always have exactly two ``sides'', referred to as A and B so as not to confuse them with sides in the game.

 -- Form: battle a-list b-list...

Each list has the form

     ((<unit> <commitment>) ...)

Types in General
================

Types are the foundation of Xconq game designs. Nearly all the rules and game parameters are associated with the unit, material, and terrain types. There is no sort of type hierarchy; instead, most forms allow sets of types to be used in the place of single types.

Each type has an index associated with it, starting from 0. This index never appears directly, and cannot be set. This does mean that types have an order, so the order in which types are defined is sometimes significant. These cases will be noted. The order is always the order in which the types appear in the file, so it is always the same.

Naming
------

The names of types need not be distinct from each other, but you run the risk of player confusion if they share names.

 -- TypeProperty: name string
     This property is the specific name of the type. This name will be displayed to players; the exact format is up to the interface, but will typically depend on the name's length and the space available in the display. If no type names have been defined, the internal type name (see below) will be used. Defaults to "".

 -- TypeProperty: long-name string
     This property is a fully spelled-out name for the type. Defaults to "".

 -- TypeProperty: short-name string
     This property is an abbreviated name of r Defaults to "".

 -- TypeProperty: generic-name string
     This property is like name, but identifies the type less specifically, and several types may have the same generic name. If no generic names are defined, then the regular type names will be used. This is useful when making abbreviated lists, so that related types get counted together. Defaults to ().

As an example of the distinction between type names and generic type name, the names of a automobile type might be "1965 Mustang", "Mustang", and "M", while the generic name is "auto". Then the interface could choose to display a parking lot as containing either "4 auto" or "2 Mustang 1 Edsel 1 Jeep".

Note that names specified as properties are strings only, and are not defined as evaluable symbols.

Imaging
-------

The interpretation of these properties is entirely up to each interface; see the appropriate interface documentation for details.

 -- TypeProperty: image-name str
     This property is the name of the type's image. If undefined or unusable for some reason, the interface will display the type in some default manner, such as a solid-color square or a string.

For example, in X11, the name might be the name of a file in the usual bitmap format, as produced by the BITMAP program.  The actual file name is produced by appending ".b". (The situation in X is actually more complicated than this.) See the interface documentation for details on how the interface uses the image.

 -- TypeProperty: color str
     This property is the name of the preferred color for this type. Both normal color names and the strings "bg" and "fg" (meaning ``foreground color'' and ``background color'') may be used. If the image is in color, then this property has no effect. Defaults to "fg".

 -- TypeProperty: char str
     This property supplies a single character for this type (all characters after the first one in STR are ignored). Defaults to "".

Documentation
-------------

 -- TypeProperty: description list...
     This property is a list of lists describing different ways in which an instance or instances of this type may be described textually. This information may be used in narrative descriptions and by some interfaces. [describe syntax of the lists - are similar to name grammars] If (), then the instance will be described in some default fashion, such as (for units) "the <side> <ordinal> <type>". Defaults to ().

 -- TypeProperty: help string
     This property is a brief (preferably one-line) description of the type. Defaults to "".

 -- TypeProperty: notes strings...
     This property is detailed documentation about the type. The formatting of the strings is up to the interface, but in general each string is a separate line, and the string "" indicates a paragraph break. Defaults to ().

Availability
------------

It may be that a set of types is larger than strictly necessary for a particular game.  You can make any type unavailable, which means that irrespective of any other controls, that type cannot come into play during a game.  You can also make it available only for particular turns.

 -- TypeProperty: available n
     If the value of this property is greater than 0, then this type is available in the game on or after turn N. If the value is less than 0, then the type is available, but only until turn -N. If the value is 0, then the type is never available. Defaults to 1, which means that the type is always available.

If a type becomes unavailable and there are units of that type in play, then they will vanish immediately.

Type Extension
--------------

It may occasionally be necessary to add new kinds of information to a type. For instance, new synthesis methods may require special data, or an interface may be able to use extra hints to improve its display. The extensions property can be used to store this kind of data.

 -- TypeProperty: extensions properties...
     This property is a catch-all for nonstandard type properties. Anything may appear here, but it will only be interpreted as much as needed, and unrecognized extensions will not be warned about (so if you misspell one, you won't hear about it).

Unit Types
==========

 -- Form: unit-type symbol properties...
     This form defines a new type of unit. The SYMBOL is required and must be previously undefined. The bindings in PROPERTIES are then added to the type one by one. If no other name properties are defined, the SYMBOL may be displayed to players (see above). You can define no more than 126 types of units.

The SYMBOL here becomes the unit type's ``internal type name'' which is guaranteed unique. To make synonyms for the internal type name, use define.

 -- GlobalVariable: u*
     This variable evaluates to a list of all unit types, listed in the order that they were defined. This list always reflects the list of types at the moment it is evaluated.

 -- GlobalVariable: non-unit
     This variable [constant?] evaluates to a value that is NOT a unit type. This is needed in several places to enable/disable features. Use of this in any other way is an error, and may or may not be detected before it causes a crash.

Unit Naming
-----------

 -- UnitTypeProperty: namer namer-id
     This property is the namer that will be used to generate names for units, if the unit's side does not have a namer, or the unit is independent and not in any country. Defaults to 0, which leaves the unit unnamed.

 -- UnitTypeProperty: assign-number t/f
     This property is true if the unit should have a serial number assigned to it by the side it belongs to. Serial numbers are maintained for each type on each side separately. Defaults to true.

Class-Restricted Unit Types
---------------------------

Sometimes the designer will want to make different sides have different types of units.  Although this can be done by setting up scenarios appropriately, that won't close all the loopholes that might allow a side to get units that should only ever belong to another side.

The first step is to define a class for each side.  For instance, a side named "Rome" might have a class "Roman", while the sides named "Aedui" and "Parisii" could both be in the class "barbarian".

 -- UnitTypeProperty: possible-sides exp
     This property restricts the unit type to only be usable by a side meeting the conditions of EXP. If EXP is a string, it restricts the unit type to only be usable by a side whose class includes a matching string. This can also be a boolean combination. Independent units belong to a side whose class is "independent". The default of "" allows the unit to belong to any side.

Self-Units
----------

The self-unit can be any type, including one that cannot act; for instance, a capital city could be the self-unit, thus making its defense all-important for a player.

 -- GlobalVariable: self-required t/f
     This variable is true if each side is required to have a self-unit at all times. Defaults to false. [this should also have a related side property]

 -- UnitTypeProperty: can-be-self t/f
     This property says that the type of unit can represent the side directly. Defaults to false.

 -- UnitTypeProperty: self-changeable t/f
     This property is true if the player can choose to change a self-unit of this type at any time. Otherwise the self-unit can be changed only if the current one dies. Defaults to false.

 -- UnitTypeProperty: self-resurrects t/f
     This property is true if when the self-unit dies, another unit of an allowable type becomes the self-unit automatically. Defaults to false.

Observe that these parameters can be used to develop various forms of backup, so that a player can start out as a capital city, resurrect as a town, change self to one of several towns, then lose when all the towns are lost.

 -- Table: control-chance-at u1 u2 -> n%

 -- Table: control-chance-adjacent u1 u2 -> n%

 -- Table: control-chance u1 u2 -> n%

 -- Table: control-distance-max u1 u2 -> dist
     This table gives the maximum distance from self-unit U1 at which units of type U2 can be controlled directly.  Units further away always act on their own (as if the doctrine said so[?]). If this value is < 0, then U1 can never directly control any other U2 on the side. Defaults to infinity.

Limiting Unit Quantities
------------------------

The effect of these is to prevent any extra units from being created or from going over to a side, regardless of the reason. This happens by either preventing player actions that would result in exceeding a limit (such as when building units), or by making the unit vanish instantly (such as when capturing a unit).

 -- GlobalVariable: units-in-game-max n
     This variable is the maximum number of all types of units, on all sides, including independents, that may exist at any time, including initially. Defaults to -1, which means that there is no limit.

 -- GlobalVariable: units-per-side-max n
     This variable is the maximum number of units (of all types together) that any side may have, at any time.  Events that would cause the limit to be exceeded, such as capturing a unit, result in either the unit vanishing or becoming independent. Defaults to -1, which means that there is no limit.

There is no limit on the number of units that may be independent.

 -- UnitTypeProperty: type-in-game-max n
     This property is the maximum total of the given type, for all sides together. Defaults to -1, which means that there is no limit.

 -- UnitTypeProperty: type-per-side-max n
     This property is the maximum number of units of the given type allowed to each side. Defaults to -1, which means that there is no limit.

Hit Points
----------

A unit's hit points determine how healthy it is. If a unit's hp goes below 1, it is either wrecked, meaning that it changes to a new type wrecked-type or else it vanishes, meaning that it is completely cleared from the world.

 -- UnitTypeProperty: hp-max n
     This property is the maximum number of hit points for (each part of) a unit. Completed units start with this many hit points. Defaults to 1.

 -- UnitTypeProperty: parts-max n
     This property declares that a unit is to be treated as an aggregate of N smaller identical units. Defaults to 1.

 -- UnitTypeProperty: wrecked-type unit-type
     This property is the type of unit that a unit with 0 hp will become. For instance, a destroyed ``fort'' might become a ``rubble pile'' unit. If its value is non-unit, then the destroyed unit just vanishes. The wrecked-type of a type must be a different type. Defaults to non-unit.

The transformation to the wrecked type does not change position or name. The transformed unit has full hp, supplies are conserved as much as possible, tooling is preserved, and any unit plan is erased. It has the same number of parts, or as many as possible if that is fewer. It may be that the wrecked type is on terrain that it cannot survive on; in that case, it will be wrecked again, repeating until the unit either vanishes or is in a viable position, or this process has been repeated more times than the number of unit types (prevents infinite loops). Any excess occupants will be removed and either placed in another nearby unit or in the open, or will vanish if there is no other option.

 -- UnitTypeProperty: hp-recovery n
     This property is the number of 1/100 hp recovered per turn. Recovery happens automatically, as opposed to repair, which requires explicit action. The amount n / 100 is recovered automatically each turn, while n mod 100 is the percent chance of recovering 1 hit point in addition. Defaults to 0.

Experience
----------

 -- UnitTypeProperty: cxp-max cxp
     This property is the maximum combat experience this type of unit can have. Defaults to 0.

Tech Levels
-----------

Before it can do anything with a type of unit, the side must have the appropriate tech level for that type, which is just a number ranging from 0 up to tech-level-max. Each type has a distinct tech level.

Tech levels always increase (since they represent abstract knowledge rather than physical plant). Tech can be transferred freely to any other side via the message tech [xref to messages].

For each unit type, the following parameters define the minimum tech levels at which sides can do various things.

 -- UnitTypeProperty: tech-to-see tl
     This property is the minimum tech level that a side must have before it can see a unit of this type. Defaults to 0.

 -- UnitTypeProperty: tech-to-use tl
     This property is the minimum tech level that a side must have in order to use this type of unit. Defaults to 0.

 -- UnitTypeProperty: tech-to-dissect tl
     This property is the minimum tech level that a side must have in order to dissect this type of unit and thereby increase its tech level. Defaults to 0.

 -- UnitTypeProperty: tech-from-dissection tl
     This property is the tech level that may be reached by acquiring a unit of this type. Since this is expressed as a minimum, repeated acquisitions have no additional effect. Defaults to 0.

 -- UnitTypeProperty: tech-to-build tl
     This property is the minimum tech level that a side must have in order to build this type of unit. Defaults to 0.

 -- UnitTypeProperty: tech-max tl
     This property is the absolute maximum tech level possible for this type. Defaults to 0.

 -- Table: tech-crossover u1 u2 -> n%
     This table is the minimum tech level for U2 that is guaranteed by a particular tech level for U1, expressed as a percentage of the tech-max for the types. For instance, if tech-crossover is 80, and the tech level for U1 is 10 out of a max of 20, and the max for U2 is also 20, then the side has a tech for U2 at least 8. Defaults to 0.

It is possible to gain some tech level just by being in the same game with a side that is more advanced.

 -- UnitTypeProperty: tech-leakage .01tl
     This property is the amount of tech level gain per turn that can happen to any side's tech level that is less than the max of all sides in the game. This only happens if at least one unit on the side has nonzero coverage of a unit on a more advanced side. Defaults to 0.

Feelings and Attitudes
----------------------

 -- UnitTypeProperty: attitudes-max n
     This property is the number of different sides that a unit can have feelings about. Defaults to 0.

Chain of Command
----------------

Some types of units can give orders to other units.

 -- Table: can-command u1 u2 -> t/f

[how does this work with control model?]

Point Value
-----------

Point values provide an abstract way to characterize the overall importance of a unit type. Point values figure into some scorekeepers, and are used by AIs.

 -- UnitTypeProperty: point-value n
     This property is the ``value'' of a unit. Defaults to 1.

Terrain Types
=============

Terrain types are associated with the cells, borders, connections, and coatings in a world.

 -- Form: terrain-type name properties...
     This form defines a new type of terrain, named by NAME. Details are similar to those for unit types.

 -- GlobalVariable: t*
     This variable evaluates to a list of all terrain types, listed in the order that they were defined.

 -- GlobalVariable: non-terrain
     This variable has a value that is guaranteed not to be a terrain type.

Terrain Subtypes
----------------

Terrain can appear in four different roles: as the interior of a cell, as a border between cells, as a connection between cells, or as a coating overlaying the normal terrain. The terrain subtype says which role a type can play.

 -- TerrainTypeProperty: subtype subtype
     This property is the role that the terrain type can appear in. Defaults to cell.

 -- GlobalConstant: cell
     This constant indicates that terrain can fill a cell. All units in the open and with an altitude of 0 are assumed to be surrounded by the cell terrain.

 -- GlobalConstant: border
     This constant indicates that the terrain can be a border.

 -- GlobalConstant: connection
     This constant indicates that the terrain can be a connection.

 -- GlobalConstant: coating
     This constant indicates that the terrain can be a coating. A coating is a temporary terrain modification. The classic example is snow, which effectively changes some kinds of terrain, but not completely and usually not permanently. Cells can have varying heaviness of each type of coating.

 -- Table: coating-depth-min t1 t2 -> n
     In order for a coating T1 to ``stick'', this table says much must be added all at once to terrain T2. A coating depth that drops below this will disappear immediately. Defaults to 0.

 -- Table: coating-depth-max t1 t2 -> n
     This table is the upper limit on coating depth. Defaults to 0.

Terrain types may have additional subtype attributes that are used only during synthesis, to select appropriate subtypes for special purposes.

 -- TerrainTypeProperty: subtype-x n
     This property is extra subtype information, used in synthesis. Defaults to no-x.

 -- GlobalConstant: river-x
     This constant indicates that synthesis methods should treat this type as a river. The terrain type may be either a border or a connection.

 -- GlobalConstant: valley-x
     This constant indicates that synthesis methods should treat this type as a valley.

 -- GlobalConstant: road-x
     This constant indicates that synthesis methods should treat this type as a road.

 -- TerrainTypeProperty: liquid t/f
     This property is true if the terrain type represents a liquid, which means that adjacent cells of liquid have the same elevation and so forth. Defaults to false.

Terrain Compatibility
---------------------

Terrain types are not always mutually compatible.

 -- Table: adjacent-terrain-effect t1 t2 -> t3
     This table specifies what will happen to a cell of type T1 adjacent to a cell of type T2.  If T3 is non-terrain, nothing will happen, otherwise it will become a cell of type T3. Defaults to non-terrain.

     t1 == t3 means no effect.

     This also specifies what will happen to a border of type T1 adjacent to a cell of type T2.  If T3 is non-terrain, then the border cannot border the cell, otherwise it will become a border of type T3 (or disappear if T3 cannot be a border). Defaults to non-terrain [a problem, will erase borders usually]

     This also specifies what will happen to a connection of type T1 in a cell of type T2.  If T3 is non-terrain, then the connection cannot be in the cell, otherwise it will become a connection of type T3 (or disappear if T3 cannot be a connection). Defaults to non-terrain [a problem, will erase connections usually]

Other Terrain Properties
------------------------

 -- TerrainTypeProperty: elevation-min dist

 -- TerrainTypeProperty: elevation-max dist
     These properties define the minimum and maximum possible values for the elevation in a cell of given terrain type. Both default to 0.

 -- TerrainTypeProperty: temperature-min n

 -- TerrainTypeProperty: temperature-max n
     These properties define the minimum and maximum possible values for the temperature in a cell of given terrain type. They default to -50 and 50.

 -- TerrainTypeProperty: wind-force-min n

 -- TerrainTypeProperty: wind-force-max n

 -- TerrainTypeProperty: clouds-min n

 -- TerrainTypeProperty: clouds-max n

Material Types
==============

Materials are materials that are manipulated in mass quantities. In general, material types just index arrays of unit supplies.

Lots of different material types can be thoroughly confusing. You should use as few as possible. The maximum number of material types is 126.

 -- Form: material-type symbol properties...
     This form defines a new type of material, named by SYMBOL. Details are similar to those for unit types.

 -- GlobalVariable: m*
     This variable evaluates to a list of all material types, listed in the same order as they were defined.

 -- GlobalVariable: non-material
     This variable has a value that is never a material type.

People
------

A material type can be designated as representing people.

 -- MaterialTypeProperty: people n
     This property is the actual number of individuals represented by 1 of a material. If 0, then the material type does not have people associated with it at all. Defaults to 0.

Multiple types of materials can represent different types of people, so for example you could have one type nomad with 10 people/material, and another type urbanite with 10,000 people/material.

The basic cell capacities for materials also constrains people materials, also there is a limit on the number of individuals.

 -- TerrainTypeProperty: people-max n
     This property is the maximum number of individuals allowed in a cell of this type of terrain. This is checked at the end of each turn; any excess will be moved into adjacent cells or disappear entirely. Defaults to -1, which allows any number of people in a cell.

Static Relationships Between Types
==================================

In general, static relationships are those that must always hold during a turn.  Xconq will usually only test these when necessary, but the code is free to do so more often.

Occupants and Transports
------------------------

A unit inside another unit is an ``occupant'' in a ``transport'', even if the ``transport'' can never move. There are two kinds of capacity.  Generic capacity is shared by all different types, while guaranteed capacity is for a particular type only.

 -- UnitTypeProperty: capacity n
     This property is the limit on the sum of sizes of units that may occupy this type of unit, not counting the exclusive capacities. Defaults to 0.

 -- Table: unit-size-as-occupant u1 u2 -> n
     This table is the ``size'' of a (full-sized) unit U1 when it is in a transport U2. Defaults to 1.

 -- Table: unit-capacity-x u1 u2 -> n
     This table is the number of units of type U2 that are guaranteed a place in a unit of type U1. Defaults to 0.

 -- Table: occupant-max u1 u2 -> n
     This table is the upper limit on the number of occupants of this type (not counting unit-capacity-x). Defaults to 0.

 -- UnitTypeProperty: occupant-total-max n
     This property is the upper limit on occupants of all types together. Defaults to -1, which allows unlimited occupancy.

A unit that is an occupant may not always have the same capabilities as when it is out in the open.

 -- Table: occupant-vision u1 u2 -> n%
     This table is the quality of U1's vision while an occupant of U2, expressed as a percentage of normal coverage. Defaults to 100.

 -- Table: occupant-combat u1 u2 -> n%
     This table is true if U1 do any combat action while an occupant of U2. Defaults to 100.

 -- Table: occupant-can-construct u1 u2 -> t/f
     This table is true if U1 can build things while an occupant of U2. Defaults to 0.

 -- Table: occupant-can-have-occupants u1 u2 -> t/f
     This table is true if U1 can have occupants of its own while an occupant of U2. Defaults to false.

Units and Terrain
-----------------

 -- Table: vanishes-on u t -> t/f
     This table is true if a unit U will disappear instantly if it somehow ends up on terrain of type T. Defaults to false.

 -- Table: wrecks-on u t -> t/f
     This table is true if a unit U will wreck instantly if it somehow ends up on terrain of type T. Defaults to false.

 -- TerrainTypeProperty: capacity n
     This property is the limit on the sum of unit sizes that may share this cell. Defaults to 1.

 -- Table: unit-size-in-terrain u t -> n
     This table is the ``size'' of a (full-sized) unit U when it is in/on the terrain T. Defaults to 1.

 -- Table: terrain-capacity-x u t -> n
     This table is the number of (full-sized) units of type U that are guaranteed to have a place in the cell. Defaults to 0.

Note that the units' sides are irrelevant; the sizes of units of all sides are added together. Limits are calculated separately for the connection and open terrain in a cell, but some unit types negate the capacity of connections.

 -- Table: capacity-negation u t -> t/f
     This table is true if when U is in the open in a cell that includes connections of type T, those connections have no capacity for units. Defaults to false.

 -- UnitTypeProperty: stack-order n
     This property is the relative position of this type of unit within a stack of different units. Larger values put units higher in the stack. The exact values are unimportant, they are just used as sort keys. The use of this value is to ensure that particular types are ``seen first'' when looking at a cell, so for instance if a truck and a city are stacked on the same cell, everybody will see the city and not the truck. The owner of these units can still see them. If the stack-order of two units is the same, then the higher-numbered type will be higher in the stack. Defaults to 0.

There is a possible bizarrity with stacking limits and units that can't see each other when in the same hex, namely that a player could be prevented from moving a unit into a cell that looks like it has enough room.

Units and Materials
-------------------

Units can carry materials.  As with occupants, there is both a generic storage space and spaces specialized for each material type.

 -- UnitTypeProperty: storage n
     This property is a unit's generic space for materials of any type. Defaults to 0.

 -- Table: material-size-in-unit u m -> n
     This table is the amount by which the given material counts against the unit's storage space. Defaults to 1.

 -- Table: unit-storage-x u m -> n
     This table is the space reserved specifically for each type of material. Defaults to 0.

Materials that represent people can damage units and/or surrender to them.

 -- Table: people-sabotage-rate?? u m -> .01hp
     This table is the attrition rate of a unit in the open in a cell with people on a hostile [define] side.

 -- Table: people-surrender-chance u m -> n%
     This table is the chance that people of type M will change sides if a unit of type U is in their cell. Defaults to 0.

Terrain and Materials
---------------------

 -- Table: terrain-storage-x t m -> n
     This table is the amount of a material M that can be accumulated in a cell with terrain T. Defaults to 0.

 -- Table: material-size-in-terrain t m -> n

Vision
======

Each unit can have two kinds of vision; generic vision or just vision that represents an aggregate of actual vision, circumstantial evidence, and whatever else, and specialized vision that works similarly, but can be given different characteristics. Also, units can spy on each other.

Both generic and specialized vision generate a ``coverage'' for each cell.  Coverage of zero means nobody is observing the cell, and it may go arbitrarily high. When a unit is sufficiently well-covered and has been seen, then it is ``under observation'', which means that view data will always be current.

 -- GlobalVariable: see-all t/f
     This variable is true if everything in the world, units, terrain, etc, is always visible at all times, including initially. It takes precedence over all other visibility and spying parameters. Defaults to false.

 -- GlobalVariable: see-terrain-always t/f
     If this variable is true, then any side that has seen the terrain of a cell will be informed if that terrain ever changes. Defaults to true.

 -- GlobalVariable: see-weather-always t/f

 -- UnitTypeProperty: see-always t/f
     This property is true when a unit is always visible after it has been seen once, so that side changes, movements, etc will be seen forever afterwards. If the unit moves into terrain that has not been seen, then that terrain also becomes seen as well. Defaults to false.

 -- UnitTypeProperty: see-occupants t/f
     This property is true when a unit's occupants are also seen whenever the unit itself is under observation. Defaults to false.

 -- UnitTypeProperty: see-action t/f
     If this property is true, then the unit's chance to be seen by other sides will be tested each time the unit acts in any way. This property is in addition to the check at the beginning of each turn. Defaults to true.

 -- UnitTypeProperty: see-movement t/f
     If this property is true, then the unit's chance to be seen by other sides will be tested each time the unit moves. see-action implies see-movement. Defaults to true.

 -- UnitTypeProperty: see-combat t/f

The people in a cell effectively view (for their side) all units in that cell. Some units can hide from the people.

 -- Table: visibility-to-people u m -> n%
     This table is the chance that the people of the given type M will see a unit of type U. This will be evaluated for each people type individually, once at the beginning of each turn, and once for each populated cell that the unit enters during the turn. Defaults to 100.

 -- TerrainTypeProperty: thickness dist
     This property is the thickness of the terrain, which is the difference between the ``ground'' of the terrain and its top. (See vision parameters for the effects of terrain thickness.) Defaults to 0.

 -- UnitTypeProperty: weather-vision-range dist
     [should be a table so can't see a long ways off from within forest?]

Generic Vision
--------------

 -- UnitTypeProperty: vision-range dist
     This property is the maximum range of vision coverage by the unit. A value of -1 disables all vision, 0 means only units in the same cell may be seen, and 1 means units in adjacent cells may be seen. Defaults to 1.

 -- UnitTypeProperty: vision-bend n
     This property is the amount by which a unit can see ``around corners''. 0 means that vision is strictly line-of-sight, while 100 means that elevations never obstruct vision. Defaults to 100.

 -- UnitTypeProperty: vision-at n

 -- UnitTypeProperty: vision-adjacent n

 -- UnitTypeProperty: vision-at-max-range n
     Each of these properties represents the amount of vision coverage provided by the unit type at various ranges. All default to 1.

 -- Table: visibility u t -> n%
     This table is the basic chance to see a unit of type U when in terrain of type T, expressed as a percentage of the coverage by the viewing side. Defaults to 100.

 -- Table: combat-visibility u1 u2 -> n%
     This table is the basic chance to see a unit of type U1 when in combat with a unit of type U2, expressed as a percentage of the coverage by the viewing side. This is evaluated for each combat action within a turn. Defaults to 100.

 -- UnitTypeProperty: lockon-chance n%
     This property is the chance that once seen, a unit will continue to be seen while it is being covered. This is effectively true for any unit with a visibility of 100. Defaults to 0.

 -- Table: eye-height u t -> dist
     This propety is the additional elevation above the unit's position that a unit can see with, when in the given terrain. Defaults to 0.

Spying
------

A unit type can also be specified to do spying automatically. The outcome of spying is calculated once/unit/turn, at the beginning of the turn (after move calculation but before any players can do anything). Spying can happen to any unit not on the spying unit's side.

 -- UnitTypeProperty: spy-chance n.f%
     This property is the chance that the unit's spies will find out something. Defaults to 0.

 -- UnitTypeProperty: spy-range dist
     This property is the maximum distance at which the unit's spies will find out something. Defaults to 0.

 -- Table: spy-quality u1 u2 -> n%
     This table gives the chance that U1's spies will return information about a unit of type U2. Defaults to 100.

 -- Table: compromise-chance u1 u2 -> n%
     This table is the chance that if U1's spies return information about a unit of type U2, then that unit will always be visible thereafter, as if it were see-always. The compromised unit and its side will not be aware that this has happened. Defaults to 0.

Game Initialization and Naming
==============================

Game initialization always starts by resetting all the game-defining data structures to an empty state.  This means no types, no world, etc. Then Xconq reads and interprets all of the game modules that have been requested. These modules may overwrite each other arbitrarily. Then any command line or startup options are processed (this may involve an interactive dialog), and the random number generator is initialized. and players are matched with sides (any sides needed for players will be created and named at this time). Xconq then executes a number of synthesis methods to do various kinds of setup.

(Some interfaces might allow for confirmation of the setup before launching into the game proper, but this cannot be assumed.)

Since the details of good game synthesis can be complicated, synthesis methods are simply wired-in pieces of code. Each method is self-contained; it assumes the game state to be valid, it will determine its own applicability and produce a valid result.  It will also acquire any data that it needs, so does not require any special setup;  however, a method may fail to run if it cannot find that data. For instance, the usual fractal terrain generator needs percentiles for each terrain type, and will not function without them.  It may be that all the requested synthesis methods fail; this is OK if Xconq's data is present and consistent, but otherwise Xconq will shut itself down, since it has no remaining alternatives (think of this as a serious programming error and fix the game design).

 -- GlobalVariable: player-mix-default form

 -- GlobalVariable: player-mix-required form

The Synthesis Method List
=========================

The synthesis method list specifies which methods will be run, and in what order. After they have all been run, Xconq runs a consistency and completeness check.  For instance, there should be a world with terrain everywhere. Failure at this point is fatal; Xconq will either exit or return to a game setup dialog.

 -- GlobalVariable: synthesis-methods method-list
     This variable is a list of synthesis methods. If the list is empty, no synthesis methods will be run.

The list of synthesis methods is ordered, but should not contain duplicates (it's conceivable that there is some reason to run a method twice, but most won't do anything if they've already been executed once).

The default synthesis method list is

     (make-fractal-percentile-terrain
      make-countries
      make-independent-units
      make-roads
      make-rivers
      init-supplies
      name-geographical-features
     )

The synthesis method list may also contain items of the form

     ("program" forms...)

For each of these items, Xconq will attempt to find and run an external program named "program", giving it as input the result of evaluating the forms, and then reading the output of the program, which must be a valid game module.  Any further details will depend on your system, since each will use different conventions. Note that this is NOT a portable construct; you cannot assume that everybody will have built and installed the program you're using.

Fractal World
-------------

 -- SynthesisMethod: make-fractal-percentile-terrain
     This method generates the terrain layer of a world. It works by generating two distinct layers of random blobs, known as the ``alt'' and ``wet'' layers, then decides on a terrain type for each cell. If elevations are defined, then this method will use the alt layer to produce elevations. [how?]

 -- GlobalVariable: alt-blob-density n

 -- GlobalVariable: wet-blob-density n
     These variables are the number of blobs to put down, at a rate of 1 per 10,000 cells. Defaults to 500.

 -- GlobalVariable: alt-blob-size n.f%

 -- GlobalVariable: wet-blob-size n.f%
     These variables are the average number of cells in a blob, expressed as hundredths of a percent of the number of cells in the world. Defaults to 100.

 -- GlobalVariable: alt-blob-height n

 -- GlobalVariable: wet-blob-height n
     These variable are the amounts by which to increment or decrement within a blob. Defaults to 1000.

 -- GlobalVariable: alt-smoothing n

 -- GlobalVariable: wet-smoothing n
     These variables specify the number of averaging steps to perform after the blobs have been generated. Defaults to 2.

 -- TerrainTypeProperty: alt-percentile-min n%

 -- TerrainTypeProperty: alt-percentile-max n%

 -- TerrainTypeProperty: wet-percentile-min n%

 -- TerrainTypeProperty: wet-percentile-max n%
     These properties are the percentiles of elevations and moistures that result in the given terrain type. Percentile ranges may overlap, in which case the earlier-defined terrain type will be used. If a cell has a alt and wet that does not fall in any of the ranges, then terrain type 0 will be used there and players will be warned. Mins defaults to 0, maxes to 100.

Maze World
----------

 -- SynthesisMethod: make-maze-terrain
     This method creates terrain that looks like a maze.

 -- TerrainTypeProperty: maze-room-occurrence n
     This property is the weighted amount of this terrain type in rooms in the maze.

 -- TerrainTypeProperty: maze-passage-occurrence n
     This property is the weighted amount of this terrain type in passageways in the maze.

 -- GlobalVariable: maze-room-density n
     This variable is the fraction of the maze that is room.

 -- GlobalVariable: maze-passage-density n
     This variable is the fraction of the area that is passageway.

Random World
------------

The random world generator just assigns terrain and elevations randomly.

 -- SynthesisMethod: make-random-terrain
     This method generates completely random terrain. It uses a simple weighting to govern how much of each terrain type appears, and makes random elevations as well.

 -- TerrainTypeProperty: occurrence n
     This property is the percentage of the world that will be of this type. Defaults to 1.

Earthlike World
---------------

Earthlike generation uses algorithms that more closely approximate realistic terrain.

 -- SynthesisMethod: make-earthlike-terrain
     This method generates terrain that approximates what actually appears on Earth.

River Generation
----------------

Rivers are borders or connections consisting of ``watery terrain'' that run downhill to regions of water.

 -- SynthesisMethod: make-rivers
     This method looks for a border or connection terrain type with a subtype-x of river-x. then uses the world's elevation data to run rivers downhill (always choosing the lowest of possible adjacent locations) until they reach cell terrain with a subtype > 0. This method will not run if there are no appropriate terrain types, nor if there is no elevation data.

 -- TerrainTypeProperty: river-chance n%
     This property is the chance that a river will start in or around a cell of this terrain type. Defaults to 0.

 -- GlobalVariable: river-sink-terrain t
     If the value of this variable is a terrain type, then a cell completely surrounded by river will be changed to be this type. Defaults to non-terrain.

Note that the algorithm computes rivers in a deterministic way, so high values of river-chance do not result in tangled rivers.

[does not use valley-x yet]

Road Generation
---------------

The road generation method makes networks of connection terrain between particular unit types, usually those resembling cities.

 -- SynthesisMethod: make-roads
     This methods synthesizes roads for an area. For any connection type of terrain, if no layer has been created for it already, and the type has a subtype-x of 3, put down roads between any pair of units whose road-chance is nonzero. The method will attempt to share road routes whenever possible, and choose terrain according to road-into-chance.

 -- Table: road-chance u1 u2 -> n%
     This table is the chance that a road will be laid, running from a unit of type U1 to one of type U2. This is not a symmmetrical relationship. Defaults to 0.

 -- Table: road-into-chance t1 t2 -> n%
     This table is the chance that a road will be chosen to pass from terrain of type T1 into terrain of type T2. Defaults to 100.

Making Countries
----------------

The make-countries method is the usual way to set up a side's starting units.

 -- SynthesisMethod: make-countries
     This method works by looking for a likely place for the country, randomly places a basic set of starting units within that area, then expands the country outwards. The parameters give you control over the mix of terrain types in the country, as well as the size and relative positions of the different countries. This method runs on any side with fewer units than it is supposed to start with, as given by the parameters below. It places groups of units at locations separated from each other by specified distances.

 -- GlobalVariable: country-radius-min dist
     This variable is the radius of the country's initial area. Defaults to -1, which allows the algorithm to calculate a ``reasonable'' country size appropriate to the given number of units.

 -- GlobalVariable: country-separation-min dist

 -- GlobalVariable: country-separation-max dist
     These variables are the minimum and maximum distances of country centers from each other, in cells. If small, countries will mostly overlap; if very large, then attempts to use small worlds will fail; if the max and min are too close to each other, placements can also fail. For both of these, a value of -1 disables their effect. Both default to -1.

The max separation bound needs to be satisfied for a country with respect to only one other country, so for instance the final layout may involve a long ``string'' of countries where the first and last countries are very far apart from each other. The minimum bound must be satisfied for all pairs of countries.

 -- TerrainTypeProperty: country-terrain-min n
     This property is the minimum amount of terrain that must be within the country's initial radius. Defaults to 0.

 -- TerrainTypeProperty: country-terrain-max n
     This property is the most terrain of the given type that may appear. If -1, then any amount may be present. Defaults to -1.

 -- UnitTypeProperty: start-with n

 -- UnitTypeProperty: independent-near-start n
     These properties set the number of units of the given type in a player's country. These units are randomly scattered within the initial radius, and the favored table (see below) decides which terrains will be used.  Units may be placed inside each other; in fact, units with no favored terrain will be made into occupants if possible.

     The independent units will be placed after the ones belonging to the side, so on the average they will get the less desirable locations in the country. Both independent and the side's units will be named using the side's namers.

 -- Table: favored-terrain u t -> n%
     This table sets the probability of the unit type being on the given type of terrain at the outset.  A value of 0 is an absolute prohibition against placing the unit on that type of terrain, thus every game must specify at least one non-zero value for some terrain type and some initial unit type. Defaults to 100.

Once the initial country area has been set up, then you can allow the countries to expand outwards. Expansion occurs at the same rate for all countries. Countries may expand into and through each other.

 -- TerrainTypeProperty: country-growth-chance n%
     This property is the chance that a country will expand onto an unclaimed cell of the given terrain type. Defaults to 100.

 -- TerrainTypeProperty: country-takeover-chance n%
     This property is the chance that a country will expand onto another country's cell of the given terrain type. Defaults to 0.

 -- UnitTypeProperty: unit-growth-chance n.f%
     This property is the chance that a unit of the given type will be placed when the country expands onto a cell. The unit will only be placed if the favored chance is also true. Defaults to 0.

 -- UnitTypeProperty: independent-growth-chance n.f%
     This property is the chance that an independent unit of the given type will be placed when the country expands onto a cell. The favored chance is also evaluated. Defaults to 0.

 -- UnitTypeProperty: unit-takeover-chance n.f%
     This property is the chance that a unit of the given type in another country and belonging to another side will be given to the growing side. Defaults to 0.

 -- UnitTypeProperty: independent-takeover-chance n.f%
     This property is the chance that an independent unit of the given type in another country will be given to the growing side. Defaults to 0.

 -- GlobalVariable: country-radius-max dist
     This variable is a cap on the country growth process. Values between 0 and country-radius-min prevent country growth entirely, while a value of -1 allows growth to encompass the entire world. Defaults to 0.

 -- UnitTypeProperty: country-units-max n
     This property is a cap on the number of units given to the side's country. Defaults to -1, which disables any limit.

 -- GlobalVariable: growth-stop-chance n%
     This variable is the chance that a country's growth will stop, if during the current [ring or round] no new cells were added to the country. Defaults to 0.

 -- TerrainTypeProperty: country-people-chance n%
     This property is the chance that the people's side will be changed to match that for the country they are in.

Making Independent Units
------------------------

For many games, it is useful to have independent units scattered randomly across the world.  For instance, gold mines and treasure hoards would be good for an exploration game, and independent castles for a medieval game.

 -- SynthesisMethod: make-independent-units
     This method scatters independent units randomly over the world. This method will not run if the specified density of independent units has already been achieved, for instance from a predefined world or from country placement. Independent units that should be inside other independents will be handled correctly.

 -- Table: independent-density u t -> n
     This table is the total number of independent units appearing throughout the world, at the rate of N per 10,000 cells of the given terrain type. Any independent units already placed are counted first, so this value represents final density. If the sum of values for a given unit type is nonzero, then at least one unit of that type will be placed, even if the world is very small (i.e. the calculation of numbers rounds up not down). Defaults to 0.

This method uses the favored-terrain table as the chance that a given unit will be placed at a randomly-chosen position, and it will keep trying different positions until a suitable one is found.

 -- TerrainTypeProperty: independent-people-chance .01n%
     This property is the chance that the people of a cell with this terrain type will be made independent. Deafults to 0.

Initial Supply
--------------

By default, all units start out empty of materials. The supply initialization method gives each unit a starting supply, according to the stockpile tables.

 -- SynthesisMethod: make-initial-materials
     This method fills unit and cell supplies to specified levels. It runs only on units actually present at the moment it runs. [what about scheduled reinforcements?]

 -- Table: unit-initial-supply u m -> n
     This table is the amount of each material that each unit will start out with. If the initial supply is greater than unit's capacity, then the unit will just be filled to capacity. Defaults to 0.

 -- Table: terrain-initial-supply t m -> n
     This table is the amount of material M that each cell with terrain T will start out with. Defaults to 0.

Naming Geographical Features
----------------------------

Although named geographical features don't affect the outcome of a game in any way, they are useful for ``color'' and for identifying locations more readably.

 -- SynthesisMethod: name-geographical-features
     This method identifies and names regions as geographical features, such as mountain ranges and islands.

 -- GlobalVariable: feature-namers feature-namer-list
     This variable is a list of feature types and their associated namers. This is used for features not intersecting any country with a namer for the feature's type.

 -- GlobalVariable: feature-types feature-expr-list
     This variable is a list of feature types that may be identified. [("lake" (group (sea shallows) 1))] [("peak" (high-point 1 1%))]

Naming Units
------------

 -- SynthesisMethod: name-units-randomly
     This method gives names to previously-unnamed units, using their usual [?] naming methods.

Making a Random Date
--------------------

 -- SynthesisMethod: make-random-date

[how is this controlled?]

Setup Postprocessing
====================

Some initialization steps will be done after all synthesis methods have been run.

Initial View
------------

By default, each side starts out knowing only what its units can normally see at the beginning of the first turn. These parameters alter that initial view.

 -- GlobalVariable: terrain-seen t/f
     This variable is true if all the terrain of the world is known initially. Defaults to false.

 -- UnitTypeProperty: initial-seen-radius dist
     This property specifies the radius of the area seen around each of the starting units. It computes visibility of terrain (cells and borders) only. Defaults to 1 (which is a no-op if the unit's vision-range is greater than or equal to 1).

 -- UnitTypeProperty: already-seen n%
     This property is the chance to see units of this type at the beginning of the game. This applies only to units belonging to another side, and on known terrain. The effect is one-time, so if an already-seen unit changes sides later on, other players will not see the change unless they observe the unit for themselves. Note that see-always does imply already-seen. Defaults to 0.

 -- UnitTypeProperty: already-seen-independent n%
     This property is like already-seen, but for independent units specifically. Defaults to 0.

Naming and Text Generation
==========================

Xconq can generate names for sides, units, and geographical features.

Naming Sides
------------

Side naming is special, because several different but related names have to be produced.

 -- Variable: side-library side-info...
     This variable is a weighted list of groups of side properties, each of which may be used to fill in a side.

The form of each side name entry is basically a subset of the side's properties:

     ([weight] ... (name "name") ... (color-scheme "colors") ...)

Each entry can include as many or as few of the attributes as desired; any missing will be filled in from the usual defaults. The optional WEIGHT is a number that adjusts the probability of selection of the given side name set; it defaults to 1, and the probability is scaled according to the sum of the weights for all the sides listed. If any property value is a namer, then the namer will be run. (Note that if multiple namers are specified, they cannot be guaranteed to coordinate with each other, so you can end up with a side noun that is inappropriate for its corresponding side name.)

Namers
------

Since one of the purposes of naming is to identify objects uniquely, any name generator should be able to maintain some memory as to what has been generated already. The objects that do this are namers.

 -- Form: namer [symbol/id] method rejects...
     This form defines an instance of a namer, with either the symbolic name or numeric id.  If either matches the name or id of an existing namer, then the old namer will be overwritten, otherwise a new one will be created. The METHOD must be one of the naming methods listed below, and REJECTS defines what names may not be produced (its exact interpretation depends on the method).

Naming Methods
--------------

As with general synthesis, Xconq has a number of naming methods available.

An implementation is free to define additional naming methods.

 -- NamingMethod: random names......
     This method picks a name from the given list of names and removes that name from the list

 -- NamingMethod: junky
     This method produces a gobbledy-gook name, very techy-looking.

 -- NamingMethod: grammar root max-length rules...
     This method defines a grammar, where ROOT is the root symbol, MAX-LENGTH is a limit on the length of the generated names (in characters), and RULES is a list of rules of the form

          (SYMBOL ([sym] [weight] SYMBOL/STRING/LIST [n] ...))

The generation process works by substituting one of the rule's alternatives for the symbol, starting with the root symbol. The probability of an alternative being selected is arrived at by adding up the optional weights WEIGHT (assuming missing weights to be 1), and choosing with a probability of the weight divided by the total sum of weights. Thus the weights need not add up to any particular value.

Strings get used directly. If a symbol in the rule's chosen expansion does not appear as the lefthand side in any rule, then it will be handled as a string, otherwise it will be expanded in turn. If the symbol matches a namer's name, then that namer will be run (passing the same object??) and its result incorporated. A list should be a list of strings and symbols, and the expansion of each will be concatenated.

 -- GlobalConstant: any
     [???]

 -- GlobalConstant: or

 -- GlobalConstant: reject
     A special rule headed by reject is a list of substrings that should not appear in a generated name; this is a convenient way to filter out particularly unlovely results.

 -- GlobalConstant: capitalize
     Directs capitalization of a nonterminal.

[text is not actually different from a namer?]

 -- Form: text [symbol/id] method rejects...

[elsewhere?]
 -- GlobalVariable: action-messages patterns

 -- GlobalVariable: event-messages patterns

Other Initialization Parameters
===============================

 -- GlobalVariable: edge-terrain
     This variable is the type of terrain to fill in on all the edges of a world. The edges of a world have little or no effect on the game, but the terrain type should be something distinctive, so that players can recognize the edges easily.  (For instance, ice is usually a good choice for edges, but probably not on a map of Antarctica!)

Actions in General
==================

The parameters in this chapter define and regulate the various actions that are available to units during a game.

Actions are always started and completed (including all of their effects) within the same turn, and a unit can only do one of them at a time.

All actions are in theory available to all units, but the parameters can be set so as to deny any action type to any unit type. See the descriptions with each action type.

All action is limited by action points. Each unit gets a certain number at the beginning of each turn and expends them in the course of doing things. The usual expenditure is one point per action, but may be more, as defined for each type of action. A unit action must always consume at least one action point.

Units can accumulate acp from turn to turn, and they can also reduce acp below zero.

 -- UnitTypeProperty: acp-per-turn acp
     This property is the basic allowance of action points that a unit gets each turn. Defaults to 1.

 -- UnitTypeProperty: acp-min acp
     This property specifies how far into ``action debt'' a unit can go during a turn before it is prevented entirely from acting. A unit with acp < 1 at the beginning of a turn cannot do anything at all. Defaults to 0.

 -- UnitTypeProperty: acp-max acp
     This property is the maximum number of action points that a unit can save up. The value -1 means that acp-max is equal to acp. Extra acp is silently lost. Defaults to -1.

 -- UnitTypeProperty: free-acp acp
     This property is the value is the amount by which the action points for some action can exceed the unit's currently available acp and still allow that action. Defaults to -1, which means enough free acp to allow any action.

Note that a unit with an acp of 0 is completely unintelligent, about like a cow patty.  Cow patties can be useful for blocking paths, hiding behind, and suchlike, and have the advantage that once they're in place, you don't have to manage them.  Other units will have to pick them up and put them down, of course.

 -- Table: material-to-act u m -> n
     This table is a minimum amount of M needed for U to be able to act. The material is not consumed. Defaults to 0.

 -- UnitTypeProperty: acp-damage-effect xxx

 -- Table: occupant-acp-effect u1 u2 -> n
     Defaults to 100.

 -- UnitTypeProperty: acp-per-turn-min acp

 -- UnitTypeProperty: acp-per-turn-max acp
     This property limits on effect of occupants, damage, etc. Defaults to 1.

Action Ordering
---------------

 -- GlobalVariable: use-side-priority t/f
     This variable is true if the sides may only act one at a time; otherwise, all sides and units may move simultaneously during a turn. Defaults to false.

 -- UnitTypeProperty: action-priority n
     This property is the order in which units of this type will act. Higher numbers act earlier. If the difference between the priority of one type and another is greater than 100, then the earlier-acting units must finish acting before the later-acting units, otherwise a player can rearrange the actual acting order as desired. Defaults to 0.

 -- GlobalVariable: actions-are-buffered t/f
     This variable is true if all the units of the same priority must specify their actions first and then execute them all at once, rather than deciding and executing before the next unit gets to act. Defaults to false.

Movement
--------

Movement is the most common sort of action. This section covers movement over open terrain; the next section discusses interaction with transports.

The general theory of movement is that a unit not in a transport crosses its current cell terrain to the edge of the cell, crosses any border terrain, and then moves into the destination cell, OR it moves onto connection terrain, travels along connection terrain to the new cell, and maybe moves off the connection. If the unit starts in a transport, then the transport may ferry the unit over some of the intervening terrain, possibly as far as the unit's destination.

A unit's basic movement rate is defined by its speed, which is a ratio of the the unit's acp. A speed of 100% means that the unit can potentially enter as many cells as it has acp, while a speed of 20% means that the unit uses at least 5 acp to enter a cell.

Movement can only succeed if several conditions are met: the unit must be able to cross the border terrain, the destination must be inside the world (but see below), it must be able to exist on the terrain of the destination.

 -- ActionType: move x y z
     This is the action that a unit performs to go from one location to another. The destination must be within the move-range of the unit.

 -- UnitTypeProperty: acp-to-move acp
     This property is the number of acp a unit uses to do one move action. Defaults to 1.

 -- UnitTypeProperty: speed mp
     This property is the basic number of movement points that a normal undamaged unit gets at the beginning of each turn. Defaults to 0.

 -- UnitTypeProperty: speed-min mp
     This property is the worst-case speed of a unit. Defaults to 0.

[following needs work again]

 -- UnitTypeProperty: hp-at-max-speed mp
     This property is the minimum number of hp at which the unit retains its max speed. Defaults to 0.

 -- UnitTypeProperty: hp-at-min-speed hp
     This property is the maximum number of hp at which the unit's speed is at its minimum. Defaults to 0.

For hp between hp-at-min-speed and hp-at-max-speed, the unit's speed will be interpolated in the obvious way.

 -- Table: mp-per-occupant u1 u2 -> n%
     This table is the percent change in the speed of type U1 for each occupant of type U2. If the basic speed of U1 is 0, then the multiplication is performed as if the speed were 1 instead. Defaults to 100.

 -- UnitTypeProperty: speed-max mp
     This property is the upper bound on a unit's movement in one turn. Defaults to 0.

 -- UnitTypeProperty: move-range n
     This property is the maximum distance allowed to the destination cell. Defaults to 1.

 -- UnitTypeProperty: speed-damage-effect xxx

Any move between cells will cost at least one movement point. Some mp costs may be negative, but the total mp for a move will always be at least 1.

 -- Table: mp-to-leave-terrain u t -> mp
     This table is the mp cost to leave a cell of type T. If T is a border type, this cost is never used. If T is a connection type, this cost is the cost of leaving the connection terrain for the open terrain of the cell. If T is a coating type, then this value adds to the cost of leaving the cell. Defaults to 0.

 -- Table: mp-to-enter-terrain u t -> mp
     This table is the mp cost to enter a cell of type T. If T is a border type, this cost is the cost of crossing the border. If T is a connection type, this cost is the cost of entering the connection terrain from the open terrain of the cell. If T is a coating type, then this value adds to the cost of entering the cell. Defaults to 1.

 -- Table: mp-to-traverse u t -> mp
     This table gives the cost to travel along a connection or border of the given type. (note that the other costs are irrelevant if unit starts and ends its movement on the connection).

     A special type of move known as a border slide can occur when the endpoints of a border touch on the start and destination cells. Sliding works like normal movement that happens to end up on a nonadjacent cell. Same rules for permissibility apply. If the value is negative, then border sliding is not possible.

     Defaults to 1.

If both enter/traverse/leave and enter/leave movement is possible, then Xconq will automatically choose the cheapest alternative.

 -- Table: mp-to-ascend u t -> mp

 -- Table: mp-to-descend u t -> mp
     These tables are the mp cost to go from the min possible elevation to the max possible elevation in the world. This is interpolated and rounded down. T is the type of terrain being left. Defaults to 0.

Each unit type has a range of altitudes within which it normally operates.

 -- Table: altitude-min u t -> n
     This table is the minimum altitude possible for each type of unit on each type of terrain. Defaults to 0.

 -- Table: altitude-max u t -> n
     This table is the maximum altitude possible for each type of unit on each type of terrain. Defaults to 0.

 -- UnitTypeProperty: mp-to-leave-world mp
     This property is an additional move cost to leave the world entirely. To leave, the unit must be within its move-range of an edge, and have sufficient mp to move into the terrain in the edge cell designated as the destination of the move. If the value is -1, then the unit may never leave. Defaults to -1.

 -- UnitTypeProperty: free-mp mp
     This property is the amount by which the move points can ``go into the red'' and still allow one more move. Defaults to 0.

ZOC is exerted only over units out in the open, has no effect on occupants, unless they leave their transport. Occupants can themselves exert a ZOC, if occupant-can-fight is true. ZOC applies to all units on a hostile side.

 -- Table: zoc-range u1 u2 -> dist
     This table is the maximum distance at which type U1 exerts a ZOC over type U2. A value of 0 means that the unit controls only its own cell, and a value of -1 means that the unit does not exert a ZOC at all. Defaults to 0.

 -- Table: zoc-into-terrain u t -> t/f
     This table is true if the unit exerts its ZOC into terrain T. Defaults to true.

 -- Table: zoc-from-terrain-effect u t -> n
     Defaults to 100.

 -- Table: mp-to-enter-zoc u1 u2 -> mp
     This table specifies extra movement points needed to enter the ZOC. -1 prevents entry entirely. Defaults to -1.

 -- Table: mp-to-leave-zoc u1 u2 -> mp
     This table specifies extra movement points needed to leave the ZOC. -1 prevents departure entirely. Defaults to 0.

 -- Table: mp-to-traverse-zoc u1 u2 -> mp
     This table specifies extra movement points needed to move within the ZOC. -1 prevents traversing entirely. Defaults to 0.

If multiple units exert a ZOC into the same cell, then the mp cost is the maximum of the different ZOC costs.

Units may use up some of their materials when they move. Consumption happens after the move action, and only for successful moves.

 -- Table: material-to-move u m -> n
     This table is the amount of each material that a unit of type U must have in order to be able to move. Defaults to 0.

 -- Table: consumption-per-move u m -> n
     This table is the amount of each material used by a unit to do one move action. The amount taken is independent of terrain. If the unit has less than the required amount of any of these materials, it is immobilized until it gets more (this is tested before each move action; note that this does not affect any other action, including entering and leaving transports). Defaults to 0.

Entering and Leaving Transports
-------------------------------

Units can be inside other units, and have units inside them, in a tree-like fashion.  There is no limit on the depth of the tree, but most occupant-transport relationships have other limits.

 -- ActionType: enter unit
     This is the action to enter the given UNIT.

 -- UnitTypeProperty: acp-to-enter-unit acp
     This property is the number of acp a unit uses to do one entry action. Defaults to 1.

 -- Table: can-enter-independent u1 u2 -> t/f
     This table is true if a unit U1 can enter an independent unit U2. Defaults to false.

Entering and leaving incur mp costs as does movment, but units with a speed of 0 may enter and leave transports.

 -- Table: mp-to-enter-unit u1 u2 -> n
     This table is the extra movement points required for U1 to enter the transport U2, and vice versa (i.e. how much of transport's time is consumed by the process). Defaults to 0.

 -- Table: mp-to-leave-unit u1 u2 -> n
     Similar to entry cost. Defaults to 0.

Note that these mp consumptions need not be symmetrical between occupant and transport, so for instance a passenger can use 2 of its mp to get on a transport, while costing the transport only one of its mp.

 -- Table: ferry-on-entry u1 u2 -> ferry-type

 -- Table: ferry-on-departure u1 u2 -> ferry-type
     This table specifies how much intervening terrain the unit U2 entering or leaving transport U1 will have to cross on its own (and thus incur the terrain's mp costs and limitations). Defaults to to-dest.

 -- GlobalConstant: over-nothing
     This constant indicates no ferrying, occupant must pay all costs to go to destination cell.

 -- GlobalConstant: over-own
     This constant indicates that the transport ferries over terrain of its own cell.

 -- GlobalConstant: over-border
     This constant indicates that the transport ferries over any border terrain also.

 -- GlobalConstant: over-all
     This constant indicates that the transport ferries to destination cell, effectively puts occupant on middle of cell, on connection terrain if necessary.

Research
--------

Research is an action performed by a unit with the sole effect of increasing its side's tech level. Research cannot be performed by independent units.

 -- ActionType: research u
     This is the action of researching the unit type U. If the action is valid, then the tech level of the side will increase. Unit types with any tech crossover will also have their tech levels adjusted.

 -- UnitTypeProperty: acp-to-research acp
     This property is the number of action points used up by one research action. Defaults to 0, which disallows research.

 -- Table: tech-per-research u1 u2 -> .01n
     This table is the gain in tech level resulting from a research action, expressed as 1/100 of a level.  Gains of less than 100 are probabilistic [should describe this concept in general, used by several parms] Defaults to 0.

 -- UnitTypeProperty: tech-per-turn-max tl
     This property is a ceiling on the total gain of tech level possible in one turn for each side and this unit type. Defaults to 9999.

Tooling Up
----------

There are several stages in the construction of a unit: tooling up, creation, and completion.  Tooling up is where the building unit prepares to build, creation is the step where the new unit comes into existence, and completion is where the new unit is brought up to being operational.

For the player, this is mostly automatic; if tooling must be done first, a user command to build will generate the appropriate actions.

Once the technology has been achieved, a unit that intends to construct other units may need to tool up. This is expressed as tool points or tp. Tool points start at zero, can be increased by tooling actions, and may gradually decline (representing wear and tear on the equipment).

 -- ActionType: toolup u
     This is the action of tooling up to build a unit of type u. The result is an increase in the tp for the acting unit.

 -- UnitTypeProperty: acp-to-toolup acp
     This property gives the number of acp needed to do a toolup action. Defaults to 0, which disallows tooling up.

 -- Table: tp-per-toolup u1 u2 -> tp
     This table is the number of tp gained by one tooling action. Defaults to 0.

 -- Table: tp-to-build u1 u2 -> tp
     This table is the number of toolup points needed before a unit of type U1 can create or build a unit of type U2. Defaults to 0.

 -- Table: tp-max u1 u2 -> tp
     This table is the maximum possible tooling. Defaults to 0.

 -- Table: tp-attrition u1 u2 -> tp
     This table is the number of .01 tool points automatically lost at the end of each turn. Defaults to 0.

 -- Table: tp-crossover u1 u2 -> n%
     This table is the effective number of tool points for U2 that is guaranteed to exist, expressed as a percentage of the tool points for U1. [copy tech-crossover description here] Defaults to 0.

Creating a Unit
---------------

When a constructing unit is tooled up, the build action creates a unit immediately and puts it in its designated location, whether inside the unit doing the building or somewhere nearby.  This new unit, however, is incomplete, representing the keel of the ship or the surveyor's lines for an airstrip.  Incomplete units are thus basically skeletons, with some unit characteristics, but unable to move or act in any way. They also cannot have any occupants [problem for traditional bases]. Time spent on construction, then, goes into finishing these incomplete units.

 -- ActionType: create-in u unit
     This action creates a new unit of type U occupying the given unit UNIT. The unit UNIT must have room for the new unit.

 -- ActionType: create-at u x y z
     This action creates a new unit of type U in the open at X,Y,Z. The cell must have room for this new unit.

 -- Table: acp-to-create u1 u2 -> acp
     This table is the acp used by U1 to create a U2. If zero, then U1 cannot create a U2. Defaults to 0.

 -- Table: separation-to-create-max u1 u2 -> dist
     This table is the maximum distance at which U1 can create U2. Defaults to 0.

 -- Table: cp-on-creation u1 u2 -> cp
     This table is the completeness of a unit of type U2 when created by a U1. Defaults to 0.

 -- Table: material-to-create u m -> n
     This table is the total amount of a material type needed to create a unit. Defaults to 0.

 -- Table: consumption-on-creation u m -> n
     This table is the amount of a material type consumed to create a unit. Defaults to 0.

 -- Table: supply-on-creation u m -> n
     This table is the amount of supply that a newly created unit gets. This supply is newly generated, does not come from anywhere else. (Note that players could cheat by creating units, taking their supply, and never completing them.) Defaults to 0.

Building a Unit
---------------

Once an incomplete unit has been created, other units can help to complete it.

 -- ActionType: build unit
     This action adds to the completeness of UNIT. If the unit becomes complete, it will be given its initial supply, acp, name, etc.

 -- Table: acp-to-build u1 u2 -> acp
     This table is the acp used up by one build action by U1 when buiding a unit of type U2. Defaults to 0.

 -- Table: cp-per-build u1 u2 -> cp
     This table is the amount of completeness of U2 added by each completion action performed by U1. If 0, then U1 cannot contribute to completing U2. Defaults to 0.

 -- Table: material-to-build u m -> n
     This table is the amount of each material that U must have in order to build anything. Defaults to 0.

 -- Table: consumption-per-build u m -> n
     Defaults to 0.

 -- Table: separation-to-build-max u1 u2 -> dist
     This table is the maximum distance allowed between a unit U1 and the incomplete unit U2 it is working on. Defaults to 0, which requires the two units to be in the same cell.

At a given point, incomplete units can make progress towards completion on their own.  This is automatic because incomplete units are unable to act, and occurs at a constant specified rate.

 -- UnitTypeProperty: cp-to-self-build cp
     This property is the minimum completeness of the unit necessary before it can work on itself. Defaults to 0.

 -- UnitTypeProperty: cp-per-self-build cp
     This property is the completeness added each turn when a unit works on itself. Defaults to 0.

 -- Table: supply-on-completion u m -> n
     This table is the minimum amount of supply guaranteed to a newly completed unit.  If not already available to the unit, it will be newly generated. Defaults to 0.

Repair
------

Units can restore their own and each other's hp by doing repairs. Repair requires a repair action. The action points for this action are taken from both the unit being repaired and the repairer (using the same table acp-to-repair). When a unit repairs itself, the action cost is counted once only.

 -- ActionType: repair unit
     This is the action of repairing the given UNIT.

 -- Table: acp-to-repair u1 u2 -> acp
     This table is the number of action points used up by U1 doing one repair action on U2. Defaults to 0, which disallows the action.

 -- Table: hp-per-repair u1 u2 -> .01hp
     This table is the hundredths of a hp that a single repair action by U1 restores to U2. The fraction of this over 100 is added to hp directly, while the < 100 fraction is added probabilistically. Defaults to 0.

Materials may be needed and/or consumed during repair. The materials will be taken from the unit being repaired, then from the repairer.

 -- Table: material-to-repair u m -> .01n
     This table is the amount of each material needed for one repair action. As with repair, the < 100 part is average, and > 100 is guaranteed. Defaults to 0.

 -- Table: consumption-per-repair u m -> .01n

The repairing unit must also not be too damaged itself to do repairs.

 -- Table: hp-to-repair u1 u2 -> hp
     This table is the minimum hp level required of U1 to repair U2. If less, then U1 is too damaged to do any repairing. Defaults to 1, which allows repair always.

Producing Materials
-------------------

Units can produce materials by explicit action.

 -- ActionType: produce m n
     This action results in a quantity N of material M coming into existence.

 -- Table: acp-to-produce u m -> acp
     This table is the acp used up by one produce action. Defaults to 0.

 -- Table: material-per-production?? u m -> n
     This table is the amount of material produced by U when acting to produce type M. Defaults to 0.

Transferring Materials
----------------------

Although most movement of materials between units happens automatically (see backdrop economy description, section xxx), players can also do it explicitly. Players can both take materials from other units, and give a unit's materials to others.

 -- ActionType: transfer unit m n
     This is the action of transferring supply to the given unit UNIT. The desired amount is N;  if M is a valid material type, then only that type will be transferred, otherwise the action will transfer all types of materials possible. The actual transfer amounts may be less than N. [If UNIT is NULL, then is equiv to discarding material?]

 -- Table: acp-to-unload u1 m -> acp

 -- Table: acp-to-load u1 m -> acp
     These tables are the number of action points used up by one material transfer action from U1 to U2. The amount is independent of the material type being transferred. If either value is 0, then the material cannot be transferred. Defaults to 0.

 -- Table: unload-max u1 m -> n

 -- Table: load-max u2 m -> n
     These two tables determine how much of material M can be transferred out of a unit of type U1 and into one of type U2 in one transfer action. The actual quantity transferred by the action is the minimum of these two values. A value of 0 disallows manual transfer. Both default to -1, which allows any amount to be transferred.

Changing Sides
--------------

 -- ActionType: change-side side
     This is the action of changing the actee's side to SIDE. The SIDE can be any allowable side, and the actee may be any unit controlled by the actor's side.

 -- UnitTypeProperty: acp-to-change-side acp
     If the value of this property is greater than 0, then this type of unit can be ordered to change to another given side. The type must also be allowed to be on the new side. Defaults to 0.

Disbanding
----------

Disbanding is the voluntary and controlled destruction of a unit, performed by the unit itself or another unit. A disbanded unit always vanishes, rather than changing to its wrecked-type.

 -- ActionType: disband unit
     This is the action of removing hp from UNIT. The unit will vanish if all its hit points are gone.

 -- Table: acp-to-disband u1 u2 -> acp
     This table is the number of action points used by the unit U1 to do a disband action on unit U2. Defaults to 0.

 -- Table: hp-per-disband u1 u2 -> hp
     This table is the number of hp lost in a disband action performed by U2. Defaults to 0, which disallows disbanding.

A disbanded unit can be scavenged for materials.

 -- Table: supply-per-disband u m -> n%
     This table is the percentage of the unit's supply that is recovered from a single disband action. If the value is zero, then the unit's supply will not be recovered by the disbanding process, and be lost permanently. If any supply remains when the unit's hp is 0, then that supply will be lost also. Defaults to 100, which means that the entire supply will be recovered on the first disband action.

Note that if an essential supply is 100% recovered before the unit is completely disbanded, then it may die from starvation first. A partly-disbanded unit may still acquire supply from nearby units, via the backdrop economy.

 -- Table: recycleable-material u m -> n
     This table is the quantity of each type of material that becomes available when a unit is completely disbanded. The materials go to transports, occupants, and nearby units, in that order. Any materials exceeding capacities of these units will be discarded. These materials become available only when the unit vanishes. Defaults to 0.

Transferring Parts
------------------

Units of variable size can transfer parts of themselves to other units, or create a new unit.

 -- ActionType: transfer-parts n unit
     This action moves N parts of the actee to UNIT, or creates a new unit if UNIT is omitted. If N is negative, this takes from UNIT instead. If the action takes all the parts of any involved unit, then it vanishes.

 -- UnitTypeProperty: acp-to-transfer-part acp
     Defaults to 0.

Changing Type
-------------

 -- ActionType: change-type u

 -- Table: acp-to-change-type u1 u2 -> acp
     Defaults to 0.

Combat
------

Xconq combat is somewhat abstract; the attacking player decides what sort of attack to mount and perhaps when to retreat, but all else happens automatically.

Combat may last longer than a single action; it is then called a battle and divided into rounds. The battle exists until one participant has a commitment of zero. Units in a battle need not attack, and no damage will occur if none do so, but they cannot move away until no longer committed.

The attacker/defender distinction applies only to a single action.

 -- ActionType: attack unit [commitment]
     This action is a direct attack on the given UNIT. The UNIT must be known to the attacking unit's side.

 -- ActionType: overrun x y z [commitment]
     Overruns are a sort of combined attack/capture/move action. The basic theory of an overrun is that the actor will attack, capture, or co-occupy the given destination. The exact effects depend on the types and sides of units in the destination.

 -- Table: acp-to-attack u1 u2 -> acp
     This table is the number of action points used up by the attacker. Defaults to 1.

 -- Table: acp-to-defend u1 u2 -> acp
     This table is the number of action points used up by the defender. Defaults to 1.

 -- Table: attack-range-min u1 u2 -> dist
     This table is the minimum distance at which a unit can attack another. Defaults to 0.

 -- Table: attack-range u1 u2 -> dist
     This table is the maximum distance at which a unit can attack another. Defaults to 1.

One round of combat consists of an attack, a reaction, and a calculation of effects.

The defender's reaction is completely automatic, and occurs as part of the attack action.  The defender's side does not get a chance to decide what to do until the next round, although doctrine can constrain the randomness somewhat.

 -- Table: attack-commit-min?? u1 u2 -> n%

 -- Table: defend-commit-min?? u1 u2 -> n%
     These tables are the minimum limits on the initial commitment to a battle. Defaults to 0.

 -- Table: attack-commit-max?? u1 u2 -> n%

 -- Table: defend-commit-max?? u1 u2 -> n%
     These tables are the maximum limits on the initial commitment to a battle. Defaults to 100.

 -- Table: attack-commit-up-max?? u1 u2 -> n%

 -- Table: defend-commit-up-max?? u1 u2 -> n%

 -- Table: attack-commit-down-max?? u1 u2 -> n%

 -- Table: defend-commit-down-max?? u1 u2 -> n%
     These tables are the maximum limits on the change to commitment to a battle. Defaults to 100.

 -- Table: surrender-chance-per-attack u1 u2 -> n%
     This table is the chance that u2 will surrender to u1 immediately upon being attacked. Defaults to 0.

 -- Table: withdraw-chance-per-attack u1 u2 -> n%
     This table is the chance that u2 will retreat from u1 immediately upon being attacked. Defaults to 0.

In an overrun action, if all the defending units are destroyed, the attacker has sufficient acp and mp, and the destination is safe to enter, then the attacker can move into the defenders' cell.

Firing is a kind of attack that can take place at a distance, involves no commitment or counterattack, and for which the type of ammo may be selected.

 -- ActionType: fire-at unit [m]
     This is the action of firing at a given UNIT. If M is given, then that type will be used as ammo, otherwise all available types will be used together.

 -- ActionType: fire-into x y [z] [m]
     This is the action of firing into the cell at X,Y. If Z is given, then the fire will be concentrated on units at that elevation. If M is given, then that type will be used as ammo, otherwise all available types will be used together.

 -- UnitTypeProperty: acp-to-fire acp
     If this property is greater than 0, this type may attack by firing. Defaults to 0.

 -- Table: acp-to-be-fired-on u1 u2 -> acp
     This table is the acp lost when a unit is being fired upon. Defaults to 1.

 -- UnitTypeProperty: range dist
     This property is the maximum distance to which a unit can fire. Defaults to 1.

 -- UnitTypeProperty: range-min dist
     This property is the minimum distance to which a unit can fire. Defaults to 0.

 -- UnitTypeProperty: elevation-at-max-range dist
     [elaborate calc to interpolate while rising and falling, basically approximating a parabola]

 -- Table: hit-falloff-range u1 u2 -> n

 -- Table: hit-at-max-range-effect u1 u2 -> n

Both attack and fire combat calculate hits in the same way.

 -- Table: hit-chance u1 u2 -> n%
     This table is the basic chance that a unit of type U1 will actually hit a unit of type U2. Defaults to 0.

 -- Table: attack-terrain-effect u1 t -> n%

 -- Table: defend-terrain-effect u2 t -> n%
     These tables specify the effect of attacker's and defender's respective terrains on hit-chance. These chances are multiplied with the basic hit chance. Default to 100.

 -- Table: cxp-hit-effect u1 u2 -> n

 -- Table: cxp-damage-effect u1 u2 -> n

 -- Table: cxp-material-effect u1 u2 -> n

 -- Table: friendly-hit-chance u1 u2 -> n%
     This table is the chance that a unit U2 on the attacker's side will be hit accidentally during an overrun or fire-into action. Defaults to 0.

[also have surrender/withdraw upon hit with no damage?]

 -- Table: damage u1 u2 -> hp
     This table is the basic amount of damage caused by a successful attack. The value is a ``dice spec'' [explain somewhere] Defaults to 1.

The damage in an attack is always prorated by commitment; the table value is for attacks at full commitment.

 -- Table: hp-min u1 u2 -> hp
     This table is the lowest hp possible for U1 from attacks by U2. Further attacks by U2 are still valid, but have no effect. Defaults to 0.

You can set a unit to use a material as ammo.

 -- Table: consumption-per-attack u1 m -> n

 -- Table: hit-by u2 m -> n
     These tables specify material consumption in combat. For each material m, the min of these two values is the amount of u1's supply used up in an attack on u2. Both default to 0.

 -- Table: material-to-fight u m -> n
     This table is a minimum of each material that is necessary to either attack or defend. Defaults to 0.

Transports can protect their occupants, or pass hits through.

 -- Table: protection u1 u2 -> n%

 -- Table: ablation u1 u2 -> n%
     This table is the amount of the hit that gets passed through to the transport's occupants. Defaults to 100.

 -- Table: stack-protection u1 u2 -> n%

 -- Table: stack-ablation u1 u2 -> n%

[transport's destruction may leave occupants stranded on hex, could do some sort of auto-escape or die if terrain is hostile use ferry-on-leave to decide]

[some occupants (like armor) should be able to take hits first, then pass to transport - total effect is armor -> unit -> occupants]

 -- Table: ambush-chance u1 u2 -> n%
     If U1 attempts to move into a cell containing U2, then a) if can't co-occupy, this table is the chance that U1 gets a chance to attack at improved odds(?), or if b) if can co-occupy, then U1 will enter the cell, then be attacked as in a).  The ambusher's plan can flag whether the unit will take ambush opportunities or not.

Several other side-effects of combat may also be defined.

 -- Table: theft-chance-per-attack?? u1 u2 -> n%

 -- Table: stealable-material?? u m -> n

 -- Table: loss-per-attack?? u1 u2 -> n%

 -- Table: retreat-chance u1 u2 -> n%
     This table is the chance that U2 will retreat if hit by U1. Defaults to 0.

[need general defns for who moves and when during combat rounds] [could potentiall acquire additional acp if move is discretionary, also get a level of flexibility about future commitment]

[need combat's effect on tooling? uu_tp_hit_effect, can be positive or negative (being hit helps recruiit soldiers) just hit tp randomly as percentage of hp]

Finally, a unit can attempt to capture another unit directly. This means that the unit's side changes to that of the capturing unit, but with no other consequences.

 -- ActionType: capture unit
     This is the action of capturing the given UNIT.

 -- Table: acp-to-capture u1 u2 -> acp
     This table is the number of acp used up by a capture action. Defaults to 0, which disallows capture.

 -- Table: capture-chance u1 u2 -> n%
     This table is the basic chance for U1 to capture U2. Defaults to 0.

 -- Table: scuttle-chance u t -> n%
     This table is the chance that a unit whose capture is guaranteed will disband itself entirely instead.  Scuttling is destructive, so unit changes to wrecked-type. Defaults to 0.

 -- Table: occupant-escape-chance u1 u2 -> n%
     This table is the chance that an occupant U1 will escape during the capture of a unit of type U2. Occupants that do not escape are either captured themselves or destroyed, depending on their type and the capturing unit's side. Defaults to 0.

 -- Table: hp-to-garrison u1 u2 -> n
     This table is the number of hp that will be taken from the capturing unit U1 in order to guard a captured U2. If the amount is the unit's full hp, then the unit will vanish and any occupants will be distributed to the captured unit, to open terrain, or will vanish themselves if there is no other option. Defaults to 0.

 -- UnitTypeProperty: attack-up-penalty?? n
     Defaults to 0.

 -- UnitTypeProperty: attack-down-penalty?? n
     Defaults to 0.

Combat experience affects a unit's ability to hit, and the seriousness of hits on itself.

 -- Table: cxp-hit-plus-max?? u1 u2 -> n%
     This table is the maximum hit modifier for attacker unit. Defaults to 0.

 -- Table: cxp-hit-minus-max?? u1 u2 -> n%
     This table is the maximum hit modifier for defender unit. Defaults to 0. The actual hit probability equals the basic hit probability, plus experience-hit-plus-max times fractional experience (i.e. experience divided by maximum experience) of the attacking unit, minus experience-hit-minus-max times fractional experience of the defending unit.

 -- Table: cxp-per-combat u1 u2 -> cxp
     This table is the number of combat experience points gained by U1 by surviving a combat round with U2. Defaults to 0.

 -- Table: cxp-per-capture u1 u2 -> ep
     This table is the number of combat experience points gained by U1 by capturing U2. Defaults to 0.

 -- UnitTypeProperty: cxp-on-capture-effect n
     This property gives the change in a unit's cxp due to being captured, expressed as a multiplier. Defaults to 100.

Detonation
----------

Detonation is a sort of cross between disbanding and combat, but is a distinct kind of action. The action specifies the location of the detonation, which may be in the unit's cell or an adjacent one. A unit that detonates either loses hp or changes to its wrecked-type. (Note that one could then have a unit that detonates multiple times.) It also effectively hits every unit in the vicinity.

 -- ActionType: detonate x y [z]
     This action detonates the actee at the given location X,Y,Z.

 -- UnitTypeProperty: acp-to-detonate acp
     This property is the number of action points used by one detonate action. Defaults to 0, which disallows detonation.

 -- UnitTypeProperty: hp-per-detonation hp
     This property is the number of hp lost in each detonation. Defaults to 0.

 -- Table: detonation-damage-at u1 u2 -> hp
     This table is the severity of U1's hit on a unit U2 in the same cell. Defaults to 0.

 -- Table: detonation-damage-adjacent u1 u2 -> hp
     This table is the severity of U1's hit on a unit U2 in an adjacent cell. Defaults to 0.

 -- Table: detonation-range u1 u2 -> dist
     This table gives the range of effect from detonation of U1. The severity falls off according to the inverse square law extrapolated from the adjacent cell damage. (1/4 severity at range 2, 1/9 at 3, etc.) Defaults to 0.

 -- Table: detonate-on-hit u1 u2 -> n%
     This table is the chance that a hit on U1 by a unit of type U2 will cause it to detonate (once). Noncombat reductions in hp, such as attrition, have no effect. Defaults to 0.

 -- UnitTypeProperty: detonate-on-death n%
     This property is the chance that if this type is about to die from a combat hit, it will detonate (once) first. Defaults to 0.

 -- Table: detonate-on-capture u1 u2 -> n%
     This table is the chance that this type will detonate before being captured by U2. Defaults to 0.

 -- Table: detonate-on-approach u1 u2 -> dist
     When a unit of type U2 on a non-trusted [?] side appears at a distance of DIST or less, then U1 will detonate. Defaults to 0.

 -- Table: detonation-accident-chance u t -> n.f%
     This table is the chance that the unit will detonate spontaneously. This is checked once/turn. [where/when?] Defaults to 0.

[should rethink??]

 -- Table: damaged-terrain t1 t2 -> n

Altering Terrain
----------------

 -- ActionType: alter-terrain x y t
     This action changes the type of the cell at X,Y to T.

 -- ActionType: add-terrain x y dir t
     This action adds a connection or border of type T to the cell at X,Y, in direction DIR.

 -- ActionType: remove-terrain x y dir t
     This action removes a connection or border of type T to the cell at X,Y, in direction DIR.

 -- Table: acp-to-add-terrain u t -> n

 -- Table: acp-to-remove-terrain u t -> n
     For auxiliary terrain types, these tables are the costs to add or remove. For cell terrain, the costs of removing the old type and adding the new type are added together.

 -- Table: alter-terrain-range u t -> n
     This table is the maximum distance at which a unit can alter terrain T. Defaults to 0, which means that the unit can change only the terrain in its own cell.

At present, all sides that have seen the terrain once will be informed about any changes.

Environmental Computation
=========================

This section describes how to set up backdrop computations on the state.

Random Parameters
-----------------

Environmental conditions may be computed randomly.

 -- TerrainTypeProperty: temperature-average n
     This property is the average temperature for each type of terrain. Defaults to 0.

 -- TerrainTypeProperty: temperature-variability n
     This property is the amount of totally random variation in the temperature in each cell. Defaults to 0.

[random clouds, etc]

[have random storms, increase chance in weather extrema if they occur]

The primary effect of clouds is to make things harder to see.

 -- UnitTypeProperty: cloud-vision-effect xxx

Wind Parameters
---------------

 -- TerrainTypeProperty: wind-force-average

 -- TerrainTypeProperty: wind-force-variability

 -- TerrainTypeProperty: wind-variability

 -- GlobalVariable: wind-mix-range
     This variable is the radius out to which winds interact. If 0, then winds in adjacent cells can vary independently of each other, and do not interact in any way. Defaults to 0.

 -- UnitTypeProperty: wind-speed-effect xxx

 -- UnitTypeProperty: wind-angle-effect xxx

Season Parameters
-----------------

 -- WorldProperty: year-length n
     This property is the number of turns in an annual cycle. If less than 2, then no seasonal effects will be calculated. Defaults to 0.

 -- WorldProperty: day-length n
     This property is the number of turns in a single day. If less than 2, then day and night will not be calculated. Defaults to 0.

Note that year-length and day-length are completely independent of each other, and it is possible to have days that are longer than years.

 -- AreaProperty: initial-year-part n
     This property is the season of the first turn in the game. Defaults to 0.

 -- AreaProperty: initial-day-part n
     This property is the hour of the first turn in the game. Defaults to 0.

[need amount of daylight, twilight, etc]

Varying Activity with the Season
--------------------------------

 -- UnitTypeProperty: acp-at-midsummer acp
     This property is the extra acp that the unit gets at polar midsummer. This property is added to the basic acp-per-turn. Defaults to 0.

 -- UnitTypeProperty: acp-at-midwinter acp
     This property is the loss of acp at polar midwinter. This property is subtracted from the basic acp-per-turn. Defaults to 0.

These values are interpolated according to the cycle's position and the unit's latitude.  Both values may be negative.

Varying Temperature with the Season
-----------------------------------

To make the temperature vary with the season, you set the high and low values at the equator and north pole, where the low is always at midwinter and the high is always at midsummer.  Xconq interpolates on both the latitude and season to arrive at the average temperature of a location. Note that the southern hemisphere will have seasons equal but opposite to those in the north (thus there are no ``south pole parameters'').

 -- GlobalVariable: temperature-at-midsummer

 -- GlobalVariable: temperature-at-midwinter

[design chapter should mention values 40, 20, 5, -40 make earthlike]

 -- TerrainTypeProperty: temperature-moderation-range distance
     This property is the radius of the area whose raw temperatures will be averaged to get the actual temperature. This can be very slow, so only values of 0 (no averaging) and 1 (average with adjacent cells) are recommended. Defaults to 0.

The defaults for these values yield reasonable values for Earth-like worlds, assuming the temperature is Centigrade.

Weather Parameters
------------------

While the seasons change relatively slowly and predictably, weather can change drastically from turn to turn. Xconq weather is based on a daily cycle of heating and cooling plus the movement of water vapor.

Weather and seasons can be defined completely independently of each other. The weather model assumes a constant basic temperature, set from summer-equator if the season model is not being used.

Atmospheric vapor is modelled by having a vapor quantity in each cell [define a layer for this]. Vapor originates with evaporation from terrain, moves around with changing winds and air pressure, and high levels result in clouds, rain, and snow.

Environmental Effects
=====================

The environmental conditions include temperature, coatings such as snow, and atmospheric conditions.

[specify these]

The current environmental conditions in each cell [or in world as a whole? or calc by regions?] derive from a combination of three calculations: random, seasons, and weather.

Coating Effects
---------------

[effects of coating should be increased attrition, decreased productivity, decreased activity and mobility]

Effects of Temperature on Units
-------------------------------

The cell's temperature affects units only if it is outside the unit's ``comfort zone''. Uncomfortable units have increased attrition, reduced acp and mp. [extra consumption?]

 -- UnitTypeProperty: survival-zone-min n

 -- UnitTypeProperty: survival-zone-max n
     These properties specify the temperatures above and below which the unit dies (vanishes?). Default to -9999 and 9999, respectively.

 -- UnitTypeProperty: comfort-zone-min n

 -- UnitTypeProperty: comfort-zone-max n
     These properties are the temperatures within which which the unit is comfortable. Default to -9999 and 9999, respectively.

Transports can protect their occupants from temperature extremes.

 -- Table: temperature-protection u1 u2 -> t/f

[any effects of temperature on material production by units and cells?]

[specify temperature attrition, generic effect, etc]

Effects of Lighting on Units
----------------------------

 -- Table: night-acp-effect u t -> n
     This table is the multiplier for unit's acp at night in each type of terrain. Defaults to 100.

 -- Table: night-vision-effect u t -> n
     This table is the multiplier for unit's vision at night in each type of terrain. Defaults to 100.

Economy
=======

The following parameters control the automatic production, distribution, and consumption of materials by units and by cells.

Unit Production and Consumption
-------------------------------

Units can be set to always produce some amount of material without taking explicit action.

 -- Table: base-production u m -> n
     This table is the basic amount of each material M produced by a unit of type U in each turn. Defaults to 0.

 -- Table: occupant-production u m -> n
     This table is the base production when unit is an occupant. Defaults to 0.

 -- Table: productivity u t -> n%
     This base is the percentage productivity of a unit on a type of terrain. This is multiplied with the basic production rate to get actual material production, so productivity of 0 completely disables production on that terrain type, and productivity of 100 yields the rate specified by base-production. Defaults to 100.

 -- Table: productivity-min u m -> n

 -- Table: productivity-max u m -> n
     These tables are the lower and upper bounds on actual production after multiplying by productivity. Default to 0 and 9999, respectively.

 -- Table: base-consumption u m -> n
     This table sets the amount of materials consumed by the unit in a turn, even if it doesn't move or do anything else. Defaults to 0.

 -- Table: hp-per-starve u m -> hp
     If the unit runs out of a material that it must consume, this table specifies how many hp it will lose each turn that it is starving. If starving for several reasons, loss is max of starvation losses, not the sum. Defaults to 0.

 -- Table: consumption-as-occupant u m -> n%
     This table is the consumption by a unit of type U1 when it is an occupant of U2, expressed as a percentage of its base-consumption. This is useful for units such as planes which always consume fuel in the air but not on the ground. Defaults to 100.

Terrain Production and Consumption
----------------------------------

Materials produced by cells can be redistributed and also taken up by units.

 -- Table: terrain-base-production t m -> n
     This table is the amount of each material produced by a cell of the given type in each turn. Defaults to 0.

 -- Table: terrain-base-consumption t m -> n
     This table is the amount of material consumed by a cell each turn. If insufficient material is available, then the terrain may change type. Defaults to 0.

 -- Table: change-on-exhaustion-chance t m -> n%
     This table is the chance that a cell will change to its exhausted type.

 -- Table: terrain-exhaustion-type t1 m -> t2
     If T2 is non-terrain, then this table says that any cell with terrain T1 that is ``exhausted'' will change to T2. If several materials are exhausted in the same turn, then the lowest-numbered material type will determine the new terrain type. Defaults to non-terrain.

 -- Table: people-base-consumption m1 m2 -> n
     This table is the base consumption per turn by people of type M1 of each other material type M2. Defaults to 0.

 -- Table: people-base-production m1 m2 -> n
     This table is the people of type M1 base production per turn of each other material type M2. Defaults to 0.

Supply Lines
------------

In real life, material production and consumption rarely occur in the same place at the same time. For some games, the player must transfer materials manually, by loading and unloading from units. However, this can be time-consuming and difficult, and is best reserved for scarce and/or valuable materials. For more common materials, Xconq provides supply lines.

 -- Table: in-length u1 m -> dist

 -- Table: out-length u2 m -> dist
     These two tables are used together to determine the length of supply lines between units.  The given type of material can only be transferred from unit type U1 to unit type U2 if the distance is less than the minimum of the in-length of U1 and the out-length of U2. For instance, the in-length for a fighter's fuel might be 3 cells, while the out-length of fuel from a city is 4 cells. Then the fighter will be constantly supplied with fuel when within 3 cells of a city. If the fighter's out-length is -1, it will never transfer any fuel to the city. An in- or out-length of 0 means that the two units must be in the same cell, while a negative length disables the automatic transfer completely. Long out-length lines should be used sparingly, since the algorithm uses the out-length to define a radius of search for units to be resupplied. Both default to 0.

 -- Table: supply-move-rate?? t m -> n
     This table says how much of material M can be moved through terrain T (cell, border, or connection) in each material transfer action. The actual limit is the minimum of all cells and borders along the supply route. A value of -1 allows any quantity to go through.

 -- Table: supply-interdiction?? u m -> n%
     This table is the reduction of supply due to the presence of an enemy unit of the given type on the supply line. A value of 100 means that the unit has no effect on supply movement, a value of 0 means that the supply line is completely cut. Defaults to 0.

Trade Between Units/Sides
-------------------------

Trade
-----

To move materials automatically between cells, you must define the demand and supply relationships, as well as the rate and distance that materials can move.

Demand for a material originates with consumption and construction needs, issuing either from a side or from some other part of the economy.

Taxation
--------

A side can set a taxation rate, which is the amount of material that will be taken from the cell-based economy and given to units on that side.

Taxes may be negative, which will have the effect of returning materials from units back to cells.

Taxation is the last step in economic calculations.

Material Conversion
-------------------

Some types of materials can be converted or combined into other types of materials.

[do by letting production vary according to consumption?]

[in general, should distinguish productive from consumptive units, specify as limits on in/out for each rtype]

Random Events
=============

[check validity of random event list after loading]

 -- GlobalVariable: random-events method-list
     This variable is a list (actually a set) of random event methods that will be run at the end of each turn.

Terrain Attrition
-----------------

Attrition is the automatic loss of hit points due to being in certain types of terrain.

 -- Method: attrition-in-terrain
     For every unit not in a transport, this method computes the chance to lose hit points, then damages the unit accordingly. This method runs once per turn.

 -- Table: attrition u t -> .01hp
     This table is the rate of loss of hp per turn. The terrain used is cell or connection terrain as appropriate for the unit's position. Defaults to 0.

Terrain Accident
----------------

Accidents result in the damage or disappearance of a unit in the open in some kinds of terrain.

 -- Method: accidents-in-terrain
     For every unit not in a transport, this method computes the chance to be hit or to vanish completely. This method runs once per turn.

 -- Table: accident-hit-chance u t -> .01n%
     This table is the chance of the unit being hit while in the given terrain. Defaults to 0.

 -- Table: accident-damage u t -> hp
     This table is the hp that will be lost in an accident. Defaults to 0.

 -- Table: accident-vanish-chance u t -> .01n%
     This table is the chance of the unit simply vanishing while in the given terrain. Defaults to 0.

Revolt
------

Revolt is a spontaneous change of side, occurring in place of a side-given unit action. The new side may be none (independence) or another side. [only if other side wants it?] [50/50 chance?]

 -- Method: units-revolt
     For each completed unit, this method decides whether the unit revolts, then changes its side.

 -- UnitTypeProperty: revolt-chance n.01%
     This property is the chance for the unit to revolt spontaneously. Defaults to 0.

Surrender
---------

 -- Method: units-surrender

 -- Table: surrender-chance u1 u2 -> n
     This table is the chance that a unit of type U1 will change its side to match the side of a unit U2 that is within the surrender-range for the two types. Defaults to 0.

 -- Table: surrender-range u1 u2 -> dist
     This table is the distance out to which a unit of type U1 will surrender to a unit of type U2. Defaults to 0.

The Random State
================

It is occasionally useful to restart the random number generator consistently.

 -- GlobalVariable: random-state n
     This variable is the state of the random number generator. If this is not used, then the initial state of the random number generator will be set in a system-dependent way.

Default Display Style
=====================

The exact style of display depends on the user interface and on user preferences, but for some games, you may want to encourage a particular style by making it be the default.

 -- GlobalVariable: unseen-char str
     This variable is the name of a character that will be used to represent unexplored terrain. Defaults to " ".

 -- GlobalVariable: unseen-color str
     This variable is the name of a color that will be used to represent unexplored terrain. Defaults to "".

 -- GlobalVariable: unseen-image-name str
     This variable is the name of an image that will be used to represent unexplored terrain. Defaults to "".

 -- GlobalVariable: grid-color str
     This variable is the name of a color to use to draw the cell-separating grid. Defaults to "".

Dates and Time
==============

You can make Xconq display game time as a calendar date, rather than as a simple turn number.

 -- GlobalVariable: calendar xxx
     This variable is the description of the calendar type that will be used. If "none", then turns will be reported numerically starting from 1.  If "usual", then our present-day Gregorian calendar will be used. (Other calendars may be supported in the future.) Defaults to ().

     This is how long a turn is, in terms of the calendar.  For instance, if the usual calendar is being used, then a time measure of "day" (and a base date of "1 Jan 1900") will result in turns "1 Jan 1900", "2 Jan 1900", etc, while a date unit of "year" will yield just "1900", "1901", and so forth. If the numeric calendar is in use, then the time measure "day" will yield "day 1", "day 2", etc.

     (Eventually it is intended to support multiples of units, such as "2 day", which will just display every other day as a turn.)

 -- Symbol: usual

 -- GlobalVariable: calendar-part-names ((n1 n2 name)...)
     This variable lists the name of each season and the turns within a year for which it is appropriate. A twelve-month year with four seasons could be

          ((0 2 "winter") (3 5 "spring") (6 8 "summer") (9 11 "autumn"))

     If any number ranges overlap, then the first match will be used, while if a particular turn has no named season, then it will go unnamed in the display. Defaults to ().

 -- GlobalVariable: initial-date
     This variable is the date, in the specified calendar system, of the first turn. Defaults to "", which has the effect of setting the initial date to be whatever the calendar does with turn number 1.

 -- GlobalVariable: turn n
     This variable is the date of the current turn. [written correctly?] Defaults to 0.

 -- GlobalVariable: last-turn n
     This variable is the date, in the specified calendar system, of the last turn. Defaults to -1, which means that there is no limit on the number of turns.

 -- GlobalVariable: extra-turn-chance n%
     This variable is the chance that the game will go one more turn after the last-turn.

Xconq is currently limited to games of 32,767 turns.

A game may also be limited in real time.

 -- GlobalVariable: real-time-for-game seconds

 -- GlobalVariable: real-time-per-turn seconds

 -- GlobalVariable: real-time-per-side seconds

 -- GlobalVariable: elapsed-real-time seconds

Miscellany
==========

 -- UnitTypeProperty: name-internal str
     Internally used type name.

Debugging
---------

 -- Form: print value
     This form prints to a console (or whatever the interface provides) the object VALUE, in GDL syntax.

AI Data
-------

These are computed and used internally by AIs.

 -- XXX: zzz-fr

 -- XXX: zzz-uaw

 -- XXX: zzz-dw

 -- XXX: zzz-ew

 -- XXX: zzz-mrs

 -- XXX: zzz-b

 -- XXX: zzz-bb

 -- XXX: zzz-transport

 -- XXX: zzz-c

 -- XXX: zzz-cm

 -- XXX: zzz-cc

 -- XXX: zzz-uh

 -- XXX: zzz-bw

 -- XXX: zzz-abt

 -- XXX: zzz-bhw

 -- XXX: zzz-bcw